AI assistants (MCP)

Wherebox has a Model Context Protocol 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:

Both offer the same tools, resources and prompts (the MCP reference 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).

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:

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

  Copy

Without a token, the endpoint answers 401 with a WWW-Authenticate header that points the client at the OAuth metadata; 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:

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:

{
  "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). 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).

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. For example, an assistant asked "where are the Chřiby hills?" might send:

{
  "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 and 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.