MCP server

The AI Search API MCP server exposes search, job, usage, surface, and watch operations as tools for agents. It uses Streamable HTTP at:

https://api.aisearchapi.dev/mcp

The server implements protocol revision 2025-06-18 and is stateless: every request gets a fresh context, with no MCP session persistence between requests.

Authentication

MCP uses the same API keys as the REST API. Send a restricted sk_live_... or sk_test_... key as a Bearer token:

Authorization: Bearer sk_live_...

A missing or invalid key returns HTTP 401, includes WWW-Authenticate: Bearer, and uses the standard flat JSON error shape:

401

{
  "code": "AUTH_INVALID",
  "error": "missing or invalid API key; send Authorization: Bearer <API_KEY>",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#auth_invalid"
}

OAuth is on the roadmap, but is not available today. MCP clients must send an API key.

Setup

Claude Code

claude mcp add --transport http aisearchapi https://api.aisearchapi.dev/mcp \
  --header "Authorization: Bearer sk_live_..."

Cursor

Add the server to .cursor/mcp.json. Cursor supports direct HTTP transport:

{
  "mcpServers": {
    "aisearchapi": {
      "url": "https://api.aisearchapi.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Claude Desktop

Claude Desktop’s configuration is stdio-oriented, so bridge to the remote server with the standard mcp-remote adapter package:

{
  "mcpServers": {
    "aisearchapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.aisearchapi.dev/mcp",
        "--header",
        "Authorization: Bearer ${AISEARCH_API_KEY}"
      ]
    }
  }
}

If your Desktop build supports native remote HTTP MCP servers, point it directly at the MCP URL with the same Authorization header instead of using the bridge.

Replace the placeholder with your real sk_live_... or sk_test_... value. Keep the key server-side and out of source control. Anyone who holds it can spend your credits; revoke and replace it immediately if exposed.

Tool catalog

Tool	What it does	Cost / latency
`search`	`{ query, surfaces?, country?, extract?, targets? }` runs a search. One surface uses the sync path; multiple surfaces poll briefly. Returns `{ surface, status, answerMarkdown, sources[], mentions, credits }` per surface.	Billed like `POST /v1/search`. A single-surface call takes ~30–60s; MCP clients should not apply a timeout under 90s.
`get_job`	`{ id }` returns the same Envelope as `GET /v1/jobs/:id`, compacted.	Free (read).
`list_jobs`	`{ limit?, status? }` returns your recent parent jobs.	Free (read).
`list_surfaces`	No args. Returns every surface, its credit cost, and whether it is live.	Free (read; unauthenticated on the REST side too).
`get_usage`	No args. Returns your credit balance and a recent usage rollup.	Free (read).
`create_watch`	Accepts the same body as `POST /v1/watches`.	Free for the watch itself; runs bill per surface when dispatched.
`list_watches`	`{ limit?, status? }` returns your watches.	Free (read).
`update_watch`	`{ id, ...fields }` applies the same update as `PATCH /v1/watches/:id`.	Free (read/write; no credit cost).
`delete_watch`	`{ id }` soft-cancels a watch.	Free.
`get_watch_runs`	`{ id, limit? }` returns a watch’s run history.	Free (read).

Every tool call proxies through the corresponding REST endpoint with the same authentication, credits, tenancy, and error semantics. The MCP layer only reshapes JSON to use fewer agent tokens; markdown answers are truncated to about 8,000 characters with a note when truncation occurs.

Errors

Tool errors map to the same stable codes, flat error shape, and docs_url values as the REST API. See Error handling for the complete catalog and retry guidance.

For AI agents

Integrate the same API directly over raw HTTP.

Create a search

The request, response, and billing contract behind the search tool.

Watches

Schedule recurring searches exposed through the watch tools.

Introduction

Guides

Authentication

Setup

Claude Code

Cursor

Claude Desktop

Tool catalog

Errors

For AI agents

Create a search

Watches

​Authentication

​Setup

​Claude Code

​Cursor

​Claude Desktop

​Tool catalog

​Errors

​Related

For AI agents

Create a search

Watches

Authentication

Setup

Claude Code

Cursor

Claude Desktop

Tool catalog

Errors

Related