# MCP server

SerpWiz runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server, so Claude, Cursor, VS Code and other MCP clients can search Google and Google Maps directly, without any glue code.

| | |
|---|---|
| **URL** | `https://api.serpwiz.com/mcp` |
| **Transport** | Streamable HTTP (stateless) |
| **Auth** | Sign in with OAuth (clients that support it), or your API key in the `X-API-Key` header |
| **Cost** | Same as the API: 1 query per successful `google_search` or `google_maps` call. Failed calls are free. |

Most clients just need the URL: they open a SerpWiz sign-in page, you approve, and they connect. For clients without sign-in, get a key from your [dashboard](/dashboard/keys). Tool calls share your account's [rate limit](/docs/rate-limits) and show up in your request logs like any other request.

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `google_search` | Live Google results: organic results, ads, top stories, knowledge panel, People Also Ask, related searches. Arguments: `q` (required), `gl`, `hl`, `page`, `tbs`. | 1 query |
| `google_maps` | Places from Google Maps: name, address, rating, reviews, phone, website, hours, coordinates. Arguments: `q`, `place_id` or `url`, plus `num` (max 20), `gl`, `hl`, `location`, `lat`, `lng`, `radius_km`, `place_details`, `reviews`, `max_reviews`, `popular_times`. | 1 query |
| `get_account` | Remaining balance, free allowance, next expiry, plan and rate limit. | Free |

Arguments behave exactly like the REST parameters. See [Google Search](/docs/google-search) and [Google Maps](/docs/google-maps).

## Claude Code

```bash
claude mcp add --transport http serpwiz https://api.serpwiz.com/mcp
```

Then run `/mcp` in Claude Code and choose **serpwiz** to sign in. To use an API key instead, add `--header "X-API-Key: sw_live_YOUR_KEY"` to the command.

## Claude and Claude Desktop (custom connector)

1. In **Settings → Connectors**, choose **Add custom connector**.
2. Paste `https://api.serpwiz.com/mcp` as the URL and click **Add**.
3. Click **Connect**, sign in to SerpWiz (or create a free account) and approve.

## ChatGPT

Add a custom connector (in developer mode) with the URL `https://api.serpwiz.com/mcp` and OAuth authentication. ChatGPT registers itself and sends you to SerpWiz to sign in and approve.

## Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (one project). With only the `url`, Cursor asks you to sign in; with the header, it uses your key:

```json
{
  "mcpServers": {
    "serpwiz": {
      "url": "https://api.serpwiz.com/mcp",
      "headers": { "X-API-Key": "sw_live_YOUR_KEY" }
    }
  }
}
```

## VS Code (GitHub Copilot)

With just the URL, VS Code asks you to sign in to SerpWiz:

```json
{
  "servers": {
    "serpwiz": { "type": "http", "url": "https://api.serpwiz.com/mcp" }
  }
}
```

Or use an API key. Add this to `.vscode/mcp.json`; VS Code asks for the key once and stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "serpwiz-key", "description": "SerpWiz API key", "password": true }
  ],
  "servers": {
    "serpwiz": {
      "type": "http",
      "url": "https://api.serpwiz.com/mcp",
      "headers": { "X-API-Key": "${input:serpwiz-key}" }
    }
  }
}
```

## Other clients

Any client that supports remote MCP servers over Streamable HTTP works. Point it at `https://api.serpwiz.com/mcp`. Clients that support MCP authorization sign in with OAuth; for the rest, send your key as an `X-API-Key` or `Authorization: Bearer` header. To check the server by hand:

```bash
curl https://api.serpwiz.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: $SERPWIZ_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"google_search","arguments":{"q":"best crm for startups"}}}'
```

## Connected apps

Apps you connect by signing in are listed with your keys under [API keys](/dashboard/keys), marked **Connected app**. **Disconnect** stops an app immediately; connecting it again takes one click. An account can have 20 keys and connected apps in total.

## For client developers

SerpWiz follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization): OAuth 2.1 with PKCE.

| | |
|---|---|
| Protected resource metadata | `https://api.serpwiz.com/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `https://serpwiz.com/.well-known/oauth-authorization-server` |
| Client registration | Dynamic client registration at `https://serpwiz.com/oauth/register`, or a client ID metadata document (an `https` URL as `client_id`) |
| Grants | `authorization_code` with PKCE (`S256`, required) and `refresh_token` |
| Scope | `api` |
| Tokens | Access tokens last 1 hour. Refresh tokens rotate on each use and expire after 90 days without use. |

A request without credentials gets `401` with a `WWW-Authenticate` header pointing to the protected resource metadata. Access tokens also work on the [REST API](/docs/api) as `Authorization: Bearer …`.

## Errors

- **Missing, invalid or expired credentials:** HTTP `401` with a `WWW-Authenticate` header, and a JSON-RPC error with code `-32001`.
- **Everything else** (a bad argument, a rate limit, an empty balance, a search that failed) comes back as a tool result with `isError: true`. The [error object](/docs/errors) inside tells the model what to fix or how long to wait. You're never charged for errors.