# AI assistants (MCP)

Wherebox has a [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI assistant such as Claude can make maps for you: it renders a map, looks at the image, refines the spec until the map is right, and then gives you a permanent image URL to embed. It can also look up ambiguous names before it renders.

There are two ways to connect:

| | Hosted endpoint | Local server |
|---|---|---|
| Runs | on the Wherebox server, at `/mcp` | on your machine: `npx @wherebox/mcp` |
| Transport | Streamable HTTP | stdio |
| Sign-in | OAuth: you approve the assistant in your browser | a secret key (`sk_…`) in `WHEREBOX_API_KEY` |
| Good for | Claude on the web, desktop and mobile, any client with remote servers | clients that only run local servers, scripts, your own server |

Both offer the same tools, resources and prompts (the [MCP reference](/docs/reference/mcp.md) lists them), and both count like the API: each newly rendered map counts toward your account's monthly allowance, while identical requests are served from the cache for free (see [fair use](/docs/guides/fair-use.md)).

## Hosted endpoint

The endpoint is `https://api.wherebox.dev/mcp`. Add it to your client as a remote (HTTP) MCP server; the first time, the client opens a browser window where you sign in to Wherebox and approve it.

- **Claude (web and desktop):** Settings → Connectors → *Add custom connector*, then paste the URL.
- **Claude Code:**

  ```bash
  claude mcp add --transport http wherebox https://api.wherebox.dev/mcp
  ```

Without a token, the endpoint answers `401` with a `WWW-Authenticate` header that points the client at the [OAuth metadata](/docs/reference/http.md#header-www-authenticate); MCP clients follow it on their own. Tokens are issued for one resource, so a token approved for the MCP endpoint does not work on the REST API (`/v1`) and the other way round. A secret key (`Authorization: Bearer sk_…`) also works, for clients that let you set headers.

To cut an assistant off, open **Connected apps** in your account and disconnect it: its tokens stop working at once, and it has to ask for your approval again.

Renders made through a connected assistant are metered per app, separately from your API keys.

## Local server

The `@wherebox/mcp` package runs the same server over stdio. It needs Node.js 20 or newer and a secret key from the console:

```bash
claude mcp add wherebox --env WHEREBOX_API_KEY=sk_your_secret_key -- npx -y @wherebox/mcp
```

Clients configured with a JSON file (Claude Desktop, Cursor, …) take the same command:

```text
{
  "mcpServers": {
    "wherebox": {
      "command": "npx",
      "args": ["-y", "@wherebox/mcp"],
      "env": { "WHEREBOX_API_KEY": "sk_your_secret_key" }
    }
  }
}
```

The key stays in your client's configuration and is only sent to the API, in the `Authorization` header. `WHEREBOX_API_URL` points the server at another Wherebox API, such as your own (see [Configuration](/docs/reference/configuration.md)). Over plain `http` the key is accepted only for `localhost`.

## Self-hosted servers

A self-hosted server has the same `/mcp` endpoint. With `WHEREBOX_AUTH=none` (the default) it is open like the rest of the API, so connect your client to `http://your-server:8080/mcp`, or run the local server with `WHEREBOX_API_URL=http://your-server:8080` and no key. With `WHEREBOX_AUTH=keys`, use a secret key, or OAuth when `WHEREBOX_PUBLIC_URL` is set (see [Self-hosting](/docs/guides/self-hosting.md)).

## What the assistant sends

`render_map` and `get_map_url` take a map spec: the same JSON as the body of `POST /v1/map`, described in the [request body reference](/docs/reference/request-body.md). For example, an assistant asked "where are the Chřiby hills?" might send:

```json
{
  "area": "Czechia",
  "pois": [{ "place": "Chřiby", "marker": { "shape": "triangle" } }],
  "neighbors": { "show": "name" },
  "lang": "en",
  "width": 468,
  "height": 280
}
```

It gets the image back to check, plus the image's permanent URL (`https://api.wherebox.dev/v1/images/<hash>.png`). The URL is content-addressed: the same spec always gives the same URL, it needs no key, and anyone with the link can view the image. That is why the tools return this URL rather than a signed `/v1/map` URL: a signed URL needs your publishable key's signing secret, which the server never stores.

When a name is ambiguous or unknown, the tool returns an error with the same `candidates` or `suggestions` as the API's [`ambiguous`](/docs/errors.md#ambiguous) and [`not-found`](/docs/errors.md#not-found) errors, and the assistant picks one (or asks you) and tries again. Running out of quota, hitting a plan limit or the rate limit also comes back as an error the assistant can explain.

The guides and the reference are available to the assistant as MCP resources (`wherebox://docs/…`), and two prompts, `locator-map` and `route-map`, start a map from a short description.