# MCP server

> Give Claude, Cursor, VS Code, ChatGPT or any MCP client live Google search through SerpKite's remote MCP server at https://api.serpkite.com/v1/mcp. One URL, your API key, eleven tools.

SerpKite runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Any MCP client that speaks streamable HTTP can connect to it and call Google search, News, Maps, Scholar, a page fetcher and more as tools. There is nothing to install or host.

| | |
| --- | --- |
| URL | `https://api.serpkite.com/v1/mcp` |
| Transport | Streamable HTTP (stateless) |
| Auth | `Authorization: Bearer skt_live_…` |
| Protocol versions | `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Billing | Same credits as the REST endpoints |

> **OAuth is planned**
> Today the server authenticates with your API key in a header. OAuth sign-in for clients that can't send custom headers is planned. Until then, use a client that lets you set headers, or the `mcp-remote` bridge shown below.

## Get a key

Create a key in the dashboard under **API keys** (see [API keys](https://serpkite.com/docs/api-keys)). For MCP use, a dedicated key with a monthly credit limit is a good idea: an agent in a loop can make many calls, and the limit caps what that key can spend. The examples below read the key from the `SERPKITE_API_KEY` environment variable.

## Claude Code

One command adds the server to Claude Code:

```bash
claude mcp add --transport http serpkite https://api.serpkite.com/v1/mcp \
  --header "Authorization: Bearer $SERPKITE_API_KEY"
```

Run `claude mcp list` to check the connection, then ask Claude something that needs fresh results ("what changed in the latest Go release?"). Add `--scope project` to write the config to `.mcp.json` so your whole team gets it, but keep the key itself out of version control.

## Claude Desktop

Claude Desktop launches local (stdio) servers from `claude_desktop_config.json`. To reach a remote server with a custom header, use the `mcp-remote` bridge, which runs through `npx`:

```json
{
  "mcpServers": {
    "serpkite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.serpkite.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${SERPKITE_API_KEY}"
      ],
      "env": {
        "SERPKITE_API_KEY": "skt_live_..."
      }
    }
  }
}
```

The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart Claude Desktop after editing it. You need Node.js installed for `npx`.

Where your plan offers **Settings → Connectors → Add custom connector**, you can add the URL there instead. Custom connectors that need a header will work without the bridge once OAuth ships.

## Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "serpkite": {
      "url": "https://api.serpkite.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SERPKITE_API_KEY}"
      }
    }
  }
}
```

Open **Cursor Settings → MCP** to check that the server is green and its tools are listed. If your Cursor version doesn't expand `${env:…}`, paste the key directly and keep the file out of git.

## VS Code

VS Code (Copilot agent mode) reads `.vscode/mcp.json`. The `inputs` block prompts for the key once and stores it securely, so it never lands in the file:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "serpkite-key",
      "description": "SerpKite API key",
      "password": true
    }
  ],
  "servers": {
    "serpkite": {
      "type": "http",
      "url": "https://api.serpkite.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:serpkite-key}"
      }
    }
  }
}
```

Start the server from the **MCP: List Servers** command, then pick the SerpKite tools in the agent tool picker.

## ChatGPT

ChatGPT can connect remote MCP servers as connectors when developer mode is enabled for your workspace. Be aware that ChatGPT's connector setup authenticates with OAuth or no auth, and may not let you add a custom `Authorization` header. Until SerpKite's OAuth support ships, ChatGPT is the one client on this page that may not be able to connect directly. For OpenAI models in your own code, use the [tool calling guide](https://serpkite.com/docs/guides/agents-tool-calling) instead, or the OpenAI Agents SDK, which accepts MCP server headers.

## Other clients

Any client that supports streamable HTTP with custom headers works with the same two values: the URL and the `Authorization` header. Clients that only support stdio can use `npx -y mcp-remote https://api.serpkite.com/v1/mcp --header "Authorization: Bearer …"` as the command, as in the Claude Desktop example.

## Tools

All tools return LLM-ready Markdown (the same output as `format: "markdown"` on the REST API) and cost the same credits as the matching endpoint.

| Tool | What it does | Inputs | Credits |
| --- | --- | --- | --- |
| `search` | Google web search: organic results, answer box, knowledge graph, People Also Ask, related searches | `q`, `country`, `language`, `location`, `page`, `time`, `num` (10, 20, 30, 50, 100), `include_content` (0–5) | 1 per page, up to 7 for `num: 100`, +1 per fetched page |
| `news` | Google News articles | `q`, `country`, `language`, `location`, `page`, `time` | 1 |
| `maps` | Places with address, rating, phone, website, coordinates | `q`, `country`, `language`, `location`, `page` | 1 |
| `scholar` | Academic papers with citations and PDF links | `q`, `country`, `language`, `location`, `page` | 1 |
| `patents` | Patent search | `q`, `country`, `language`, `location`, `page` | 1 |
| `shopping` | Products with prices and merchants | `q`, `country`, `language`, `location`, `page` | 1 |
| `images` | Image search | `q`, `country`, `language`, `location`, `page` | 1 |
| `videos` | Video search | `q`, `country`, `language`, `location`, `page` | 1 |
| `autocomplete` | Query suggestions | `q`, `country`, `language`, `location`, `page` | 0.5 |
| `webpage` | Fetch a public URL and return its main content as Markdown with metadata | `url` | 1 |

`q` is required on every tool except `webpage`, which requires `url`. `time` is one of `hour`, `day`, `week`, `month`, `year`. As with the REST API, failed and empty calls are not billed.

## Test it with curl

The server is stateless: every `POST` carries one JSON-RPC 2.0 message (or a batch of up to 20) and gets a JSON reply. No session setup is needed, which makes it easy to test by hand.

Initialize:

```bash
curl https://api.serpkite.com/v1/mcp \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

List the tools:

```bash
curl https://api.serpkite.com/v1/mcp \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

Call `search`:

```bash
curl https://api.serpkite.com/v1/mcp \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"q":"best espresso machine 2026","country":"us"}}}'
```

The result's `content` array holds a `text` item with the Markdown. Notifications (messages without an `id`) get an empty `202 Accepted`. A missing or invalid key returns `401` with the usual [error body](https://serpkite.com/docs/errors).

## Costs and safety

- Every tool call is a billed API request, visible in the dashboard request log like any other call.
- Give the MCP key a monthly `credit_limit` so a runaway agent loop stops at a known cost. When the limit is hit, calls fail with `key_limit_reached` and nothing more is charged. See [Spend controls](https://serpkite.com/docs/spend-controls).
- The server only fetches public, logged-out pages. The `webpage` tool refuses private network addresses.

## Related

- [MCP integration overview](https://serpkite.com/integrations/mcp): Setup walkthroughs and use cases for Claude, Cursor and ChatGPT.
- [Tool calling without MCP](https://serpkite.com/docs/guides/agents-tool-calling): Define a search tool directly for OpenAI and Anthropic models.
- [Output formats](https://serpkite.com/docs/output-formats): What the Markdown the tools return looks like.
- [API keys](https://serpkite.com/docs/api-keys): Create a dedicated key with a monthly limit.