# MCP server

> Connect an MCP client to AI Search API and use search, job, usage, surface, and watch tools without writing raw HTTP calls.

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

```text
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:

```http
Authorization: Bearer sk_live_...
```

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

```json 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"
}
```

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

## Setup

### Claude Code

```bash
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:

```json
{
  "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:

```json
{
  "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.

<Warning>
  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.
</Warning>

## 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](/guides/errors) for the complete catalog and retry guidance.

## Related

<CardGroup cols={2}>
  <Card title="For AI agents" icon="robot" href="/for-ai-agents">
    Integrate the same API directly over raw HTTP.
  </Card>
  <Card
    title="Create a search"
    icon="magnifying-glass"
    href="/api-reference/search"
  >
    The request, response, and billing contract behind the search tool.
  </Card>
  <Card title="Watches" icon="satellite-dish" href="/guides/watches">
    Schedule recurring searches exposed through the watch tools.
  </Card>
</CardGroup>