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 for connecting a client.

Tools#

Tool	Annotations	Description
`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.
`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.
`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.
`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 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 code, detail, and the candidates, suggestions or issues.

Input schema of search_areas and search_places:

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