# geosearch MCP server

An MCP server for coding agents and LLM pipelines that need UK places: search, describe a point, resolve a list of messy place names, and link to a map.

Status: live.

URL: `https://geosearch-tlm25zrwea-nw.a.run.app/mcp` (Streamable HTTP, stateless: POST only, JSON replies, no session ID)
Auth: header `X-API-Key: <key>` on every request. It uses the same key and rate limit as the API: one request per search or describe call, one per query for resolve_places, none for map_link.

## Install

Claude Code:
```sh
claude mcp add --transport http geosearch https://geosearch-tlm25zrwea-nw.a.run.app/mcp --header "X-API-Key: YOUR_KEY"
```

Cursor (`~/.cursor/mcp.json`), VS Code (`.vscode/mcp.json`, key `servers`, with `"type": "http"`), Windsurf (`~/.codeium/windsurf/mcp_config.json`, `serverUrl`):
```json
{"mcpServers": {"geosearch": {"url": "https://geosearch-tlm25zrwea-nw.a.run.app/mcp", "headers": {"X-API-Key": "YOUR_KEY"}}}}
```

## Tools

- `search_places(query, limit?, lat?, lon?)`: `limit` 1–50, default 5. Returns the GET /search response.
- `describe_location(lat, lon, kinds?, limit?)`: `kinds` is a list from settlement, street, feature, poi (default all). Returns the GET /reverse response.
- `resolve_places(queries, lat?, lon?)`: up to 100 queries in one call. Returns `{rows: [{query, best, confidence, tied, more, error}], attribution}`, where `tied` holds up to three equally good right answers. The whole batch is charged against the rate limit up front, so it's admitted or refused as a unit.
- `map_link(lat, lon, zoom?, markers?)`: `zoom` 5–19, default 14; `markers` is a list of `{lat, lon, label}`. Returns `{url}`, a map with pins to show a person where something is.

## Using the results

- When several `answer: true` results share the same name in different places, they're equally good places, so ask the user which one they meant rather than guessing. Take `kind` into account (a city usually beats a pub with the same name). `more: true` means not all of them fitted.
- Low `confidence` means a person (or you) should check the row. Above 0.7 the score reads as a probability; below that, check.
- Show `attribution` with any results you display.