# MCP server

Tools, resources and prompts of the Wherebox MCP server (`packages/mcp`). The hosted endpoint `/mcp` (Streamable HTTP, OAuth) and the local server `npx @wherebox/mcp` (stdio) are built from the same definitions. See the [MCP guide](/docs/guides/mcp.md) for connecting a client.

## Tools

| Tool | Annotations | Description |
|---|---|---|
| <a id="tool-render_map"></a>`render_map` | readOnlyHint: true, idempotentHint: true, openWorldHint: false | Render a static map image and return it, so you can see it, together with its permanent public URL. Use this to design a map: look at the image and call again with a refined spec until it is right. Arguments are a Wherebox MapSpec: give at least one of `area` (a name or an id such as `iso:CZ-72`, `osm:r51684`), `pois`, `routes` or `bounds`. Defaults: 600×400 CSS px, PNG, the shaded-relief basemap, labels in local language (`lang` for others). Points take `lat`+`lon` or a `place` name; routes take `from`/`to` and default to a geodesic line (routed `car`/`bike`/`foot` profiles need a routing engine and plan). Each new map counts as one render toward the monthly quota; repeating an identical spec is served from cache for free. Ambiguous or unknown names come back as an error listing candidates or close matches. |
| <a id="tool-get_map_url"></a>`get_map_url` | readOnlyHint: true, idempotentHint: true, openWorldHint: false | Render a map (or reuse the cached one) and return only its permanent, public image URL (`/v1/images/<hash>.<ext>`) for embedding in Markdown, HTML or documents, without the image bytes. The URL is content-addressed: it never changes for the same spec, needs no key, and anyone with it can view the image. Arguments are a Wherebox MapSpec: give at least one of `area` (a name or an id such as `iso:CZ-72`, `osm:r51684`), `pois`, `routes` or `bounds`. Defaults: 600×400 CSS px, PNG, the shaded-relief basemap, labels in local language (`lang` for others). Points take `lat`+`lon` or a `place` name; routes take `from`/`to` and default to a geodesic line (routed `car`/`bike`/`foot` profiles need a routing engine and plan). Each new map counts as one render toward the monthly quota; repeating an identical spec is served from cache for free. |
| <a id="tool-search_areas"></a>`search_areas` | readOnlyHint: true, idempotentHint: true, openWorldHint: false | Find admin areas (countries, regions, districts, municipalities) by name. Each result has a `ref` (e.g. "osm:r439539") to pass as `area` or `highlight.subArea`, its admin level, and `context`: its parent areas ("Česko › Liberecký kraj › …"), which tells same-named areas apart. Use it before rendering when a name may be ambiguous. |
| <a id="tool-search_places"></a>`search_places` | readOnlyHint: true, idempotentHint: true, openWorldHint: false | Find named places (cities, villages, peaks, mountain ranges…) by name. Each result has coordinates and `context`: the areas containing it, which tells same-named places apart. Pass the chosen place as `{"lat": …, "lon": …}` in `pois` or route `from`/`to` (exact), or by `place` name when the name is unique. |

`render_map` and `get_map_url` take a MapSpec, the same JSON as the [request body](/docs/reference/request-body.md) of `POST /v1/map`. The advertised input schema (13720 bytes, budget 14000) is generated from it without examples, with repeated parts in `$defs`, and without these less common fields, which are still accepted: `shapes`, `font`, `quality`, `attribution`, `globe`, `basemap.styleUrl`, `basemap.providerKey`, `routes[].geometry`, `routes[].polyline`, `routes[].polylinePrecision`, `routes[].provider`, `routes[].casingColor`, `routes[].casingWidth`, `routes[].opacity`, `routes[].start.labelWeight`, `routes[].start.labelSize`, `routes[].finish.labelWeight`, `routes[].finish.labelSize`, `pois[].labelWeight`, `pois[].leader`, `marker.strokeColor`, `marker.strokeWidth`, `marker.icon`, `marker.anchor`, `title.position`, `title.align`, `title.size`, `title.weight`, `title.color`, `title.background`, `title.dividerColor`, `title.dividerWidth`, `title.padding`, `highlight.subdivisionColor`, `highlight.subdivisionWidth`, `highlight.subAreaColor`, `highlight.subAreaOpacity`, `highlight.subAreaOutlineWidth`, `highlight.outlineWidth`, `neighbors.size`, `neighbors.color`, `neighbors.uppercase`, `neighbors.max`, `logo`, `legend.size`, `legend.color`, `legend.background`, `legend.badgeColor`, `legend.badgeTextColor`.

`render_map` returns the image (inline up to 1 MiB) and a text block with its permanent URL; `get_map_url` returns only the URL. Errors are tool results with `isError: true` whose text carries the [error](/docs/errors.md) code, `detail`, and the `candidates`, `suggestions` or `issues`.

Input schema of `search_areas` and `search_places`:

```text
{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":200,"description":"Name to look up, in any language or spelling (accents optional), e.g. \"Zlínský kraj\", \"Chriby\"."},"limit":{"default":10,"description":"Most results to return.","type":"integer","minimum":1,"maximum":50}},"required":["q"]}
```

## Resources

The guides and this reference, as `text/markdown`. Links between pages point at these URIs.

| URI | Title |
|---|---|
| `wherebox://docs/README.md` | Wherebox documentation |
| `wherebox://docs/guides/authentication.md` | Authentication (hosted service) |
| `wherebox://docs/guides/errors-and-limits.md` | Errors and limits |
| `wherebox://docs/guides/fair-use.md` | Fair use |
| `wherebox://docs/guides/getting-started.md` | Getting started |
| `wherebox://docs/guides/locator-maps.md` | Locator maps |
| `wherebox://docs/guides/mcp.md` | AI assistants (MCP) |
| `wherebox://docs/guides/neighbors.md` | Neighboring countries |
| `wherebox://docs/guides/points-and-labels.md` | Points and labels |
| `wherebox://docs/guides/routes.md` | Routes |
| `wherebox://docs/guides/sdk-python.md` | Python SDK |
| `wherebox://docs/guides/sdk-typescript.md` | TypeScript SDK |
| `wherebox://docs/guides/self-hosting.md` | Self-hosting |
| `wherebox://docs/guides/typography-and-titles.md` | Typography and titles |
| `wherebox://docs/guides/use-cases.md` | Recipes by use case |
| `wherebox://docs/reference/README.md` | API reference |
| `wherebox://docs/reference/configuration.md` | Configuration |
| `wherebox://docs/reference/errors.md` | Errors |
| `wherebox://docs/reference/http.md` | HTTP: endpoints, auth parameters and headers |
| `wherebox://docs/reference/markers.md` | Markers |
| `wherebox://docs/reference/mcp.md` | MCP server |
| `wherebox://docs/reference/metrics.md` | Metrics |
| `wherebox://docs/reference/parameters.md` | Query parameters |
| `wherebox://docs/reference/presets.md` | Basemap presets |
| `wherebox://docs/reference/request-body.md` | Request body |

## Prompts

| Prompt | Arguments | Description |
|---|---|---|
| `locator-map` | `subject`, `notes` | Make a "where is it" map: a place or area shown inside its country or region, Wikipedia locator style. |
| `route-map` | `from`, `to`, `notes` | Draw a route or flight line between two places, with labeled ends. |

## Server instructions

Sent to the client in the `initialize` result:

> Wherebox renders static map images: locator maps (an area highlighted, its surroundings faded), labeled points, route and flight lines, and labels for neighboring countries. A map is described by one JSON MapSpec.
>
> Workflow: call render_map, look at the returned image, and refine the spec (size, labels, highlight, framing) until it is right; then use the permanent image URL it returns, or call get_map_url, to embed the map (Markdown, HTML &lt;img&gt;, documents).
>
> Names can be ambiguous ("Nová Ves") or unknown: the tool error lists candidates with a `ref` to pass as `area`, or close matches. Use search_areas / search_places to look names up first when unsure, and prefer the returned `ref` ids and coordinates over names.
>
> The guides and the full reference are available as resources (wherebox://docs/…), including fields the tool schema leaves out (shapes, fonts, title styling, routes from your own geometry).