Set up your agent

Aimnis is a hosted MCP server — most agents connect with just a URL. No key needed to start.

Endpoint: https://aimnis.com/mcp (MCP, streamable HTTP)
Keyless: works out of the box — cached answers free and unlimited, plus a daily allowance of live searches. In the snippets below, just leave the auth header out.
Auth (optional, raises limits): Authorization: Bearer aim_… or X-API-Key: aim_… — free key: ask your agent to call the register tool, or get one by email.
Tools: search (cached/live web answers, cited) · stats (pool metrics) · register (free key, in-band)

OpenCode

Add a remote MCP server to your opencode.json:

// opencode.json (project) — or the mcp block of your global config
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "aimnis": {
      "type": "remote",
      "url": "https://aimnis.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer aim_YOUR_KEY" }
    }
  }
}

OpenCode's built-in websearch is off unless you use the OpenCode provider or set OPENCODE_ENABLE_EXA — leave those off and the model reaches for Aimnis naturally. Tools appear as aimnis_search / aimnis_stats.

OpenClaw

Register Aimnis under mcp.servers in ~/.openclaw/openclaw.json (or: openclaw mcp add aimnis --transport streamable-http --url https://aimnis.com/mcp):

// ~/.openclaw/openclaw.json — under mcp.servers
{
  "mcp": {
    "servers": {
      "aimnis": {
        "transport": "streamable-http",
        "url": "https://aimnis.com/mcp",
        "headers": { "Authorization": "Bearer aim_YOUR_KEY" }
      }
    }
  }
}

To make Aimnis the only web search, disable the managed one:

// same file — make Aimnis the only web search:
{ "tools": { "web": { "search": { "enabled": false } } } }

Verify connectivity with openclaw mcp doctor --probe.

Hermes Agent

Add Aimnis under mcp_servers in ~/.hermes/config.yaml; Hermes resolves ${VAR} placeholders from ~/.hermes/.env:

# ~/.hermes/config.yaml  (put AIMNIS_KEY=aim_YOUR_KEY in ~/.hermes/.env)
mcp_servers:
  aimnis:
    url: "https://aimnis.com/mcp"
    headers:
      Authorization: "Bearer ${AIMNIS_KEY}"

To route all search through Aimnis, disable the built-in web toolset:

# same file — hide the built-in web_search / web_extract:
agent:
  disabled_toolsets:
    - web

Tools appear as mcp_aimnis_search / mcp_aimnis_stats. Reload a live session with /reload-mcp.

Pi

Pi has no native MCP client; the pi-mcp-tools extension bridges it:

pi install npm:@zhafron/pi-mcp-tools
// ~/.pi/agent/settings.json (project: .pi/settings.json)
{
  "mcp": {
    "aimnis": {
      "type": "remote",
      "url": "https://aimnis.com/mcp"
    }
  }
}

If your pi-mcp-tools version doesn't support auth headers on remote servers yet, use the REST route below instead.

Or skip MCP entirely — Pi's idiomatic path is a CLI the agent calls via bash. Put this in your project's AGENTS.md ("use this command for web searches") :

export AIMNIS_KEY=aim_YOUR_KEY
curl -s https://aimnis.com/v1/search \
  -H "Authorization: Bearer $AIMNIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your question"}'

Claude Code

claude mcp add --transport http aimnis https://aimnis.com/mcp \
    --header "Authorization: Bearer aim_YOUR_KEY"
// .claude/settings.json — prefer Aimnis over the built-in web search:
{ "permissions": { "deny": ["WebSearch"] } }

Any other agent (REST)

Anything that can make an HTTP request can use Aimnis — POST /v1/search returns structured JSON plus a ready-to-render formatted field. Keyless works here too: drop the Authorization header and you get the same free tier as MCP.

curl -s https://aimnis.com/v1/search \
  -H "Authorization: Bearer aim_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do I undo the last git commit but keep changes staged"}'

Building a product on this, not an agent? The REST API reference is written for you: request options (cache_only + prewarm_on_miss for a guaranteed-fast path that still builds the entry in the background, match/ max_distance to refuse question substitution, distill:false to skip answer generation and get citations in ~1s instead of ~20s), POST /v1/prewarm for bulk fire-and-forget warming, freshness/TTL policy, and the versioned response schema — machine-readable at /v1/schema/search.json, no key needed.

Good to know