AI agents and MCP — Overspan documentation

MCP (the Model Context Protocol) is the open standard AI assistants use to call external tools. An MCP server exposes tools; the assistant reads the list and calls them as a conversation needs them. overspan-mcp is a small TypeScript server that turns this API into those tools. It is on npm, open source (MIT), and listed in the official MCP registry as dev.overspan/mcp.

Install

You need an API key. Then it is one config entry.

Claude Code

terminal

claude mcp add overspan --env OVERSPAN_API_KEY=YOUR_KEY -- npx -y overspan-mcp

Claude Desktop, Cursor, and other JSON-configured clients

mcpServers block

{
  "mcpServers": {
    "overspan": {
      "command": "npx",
      "args": ["-y", "overspan-mcp"],
      "env": { "OVERSPAN_API_KEY": "YOUR_KEY" }
    }
  }
}

The key must be in the server's env block: MCP clients start servers with their own environment, so a variable exported in your shell profile will not reach it. Treat any config file containing the key as a secret. In Claude Code's .mcp.json you can write "OVERSPAN_API_KEY": "${OVERSPAN_KEY}" to keep the key in your environment and out of the file.

The tools

Tool	What it does
overpass_query	Run raw Overpass QL. The escape hatch when the helpers are too narrow.
find_nearby	Features matching tag filters within a radius of a point.
features_in_bbox	Features matching tag filters inside a bounding box.
count_features	Count matches in an area without returning them. Cheap; agents should call it before pulling unknown result sizes.
get_usage	The key's tier, limits, month-to-date quota, and recent requests. Never consumes quota.

The server also exposes two resources the model can read (an Overpass QL cheat sheet, and the differences from the public servers) and one prompt that steers the model toward cheap, bounded queries.

Behaviour worth knowing

The key travels as an Authorization: Bearer header, never in a URL.
Every successful result carries a quota line ([quota] 49998 of 50000 monthly requests remaining) so an agent can pace itself without asking.
Errors come back in plain language: the gateway's error code, what it means, and whether to retry. A 429 tells the agent to honour Retry-After; an exhausted monthly quota tells it not to retry until next month.
Oversized responses are trimmed to fit a model's context: the element list is cut and the result says how many elements were dropped, rather than truncating silently.
Without a key the server still starts and lists its tools; every tool call then explains where a key comes from. Nothing hard-fails in your client while you are setting up.
Queries without [timeout:] get 25 seconds. Set it explicitly for heavy queries, up to your tier's cap.

Environment variables

Variable	Required	Default	Purpose
OVERSPAN_API_KEY	yes		Your API key
OVERSPAN_API_URL	no	https://api.overspan.dev	Override the API endpoint
OVERSPAN_MAX_RESPONSE_CHARS	no	48000	Truncation threshold for tool results

Agents and your quota

An agent will happily issue fifty queries to answer one question, so the caps matter more here than for a human at a keyboard. What protects you: the damage is bounded by your tier, never by your card. Every accepted request costs one unit of monthly quota, rejected requests cost nothing, and nothing bills as overage. A runaway loop hits your rate or concurrency cap and gets 429s with a Retry-After header. The quota line on every result and the free get_usage tool exist so a well-behaved agent never gets that far.

Other MCP servers and frameworks

Any tool that lets you set an Overpass URL works with this API; what you give it depends on what it appends, and the quickstart's client section covers the forms. If you are wiring Overpass into an agent loop yourself, the quickstart's plain Python snippet is the whole integration. For agents that discover APIs on their own, the service describes itself at /.well-known/api-catalog, /openapi.json, and /auth.md.

Something here wrong, unclear, or missing? Mail hello@overspan.dev. Documentation gaps are treated as bugs.

Use Overspan from an AI agent