MCP for agents

MCP (Model Context Protocol) is a standard way for an AI agent to use outside tools. Connect gmaps.dev once, and your agent can find places, follow a collection and hand you a file on its own.

The address is https://api.gmaps.dev/mcp. Your agent uses the same API key as your code, sent the same way, in an Authorization: Bearer header. Add this block to its MCP settings:

{
  "mcpServers": {
    "gmaps.dev": {
      "type": "http",
      "url": "https://api.gmaps.dev/mcp",
      "headers": { "Authorization": "Bearer ${GMAPS_API_KEY}" }
    }
  }
}

• In Claude Code, save it as .mcp.json at the root of your project. Claude Code fills in ${GMAPS_API_KEY} from your environment, so the file never holds the key.
• In another client, add the same address and header where it keeps its MCP servers. If it doesn't fill in ${GMAPS_API_KEY} by itself, write your key there instead, and keep that file out of git.
• When you create a key under API keys, the console shows this block with that key already in it.

Your agent sees 18 tools. Each one is an API call under another name, with the same fields:

One API call has no tool: GET /v1/collections/{id}/places. A page of whole places would fill your agent's context, the text it can hold at once. So it reads places through search_places, and hands you many of them as an export.

The webhook tools need a paid plan. get_attributions needs no key, and neither does asking for the list of tools.

The server sends these steps to your agent when it connects. They're here so you know what it will do:

1. It starts with search_places: what to look for and one area. That answers at once, for free, with the places we have saved. If they don't fill limit, a collection starts to find the rest.
2. A collection takes a few minutes. The agent checks it with get_collection, then runs the same search again. The new places come back, and this time they're free.
3. For a whole city, it runs quote_collection first. That's free and says the most the collection can cost. Then it calls create_collection with maxPlaces.
4. To hand places to you, it makes an export with create_export and gives you the link. The link opens a csv, json or xlsx file for 24 hours, and the places never pass through the agent's context.
5. get_place reads one place we have saved, by our id, its cid, its place ID or a Maps link. It never searches.
6. get_usage shows the credits left today and this month. create_webhook tells your server when a collection ends, so nothing has to keep checking.

Some agents read docs instead of calling tools. For them, we publish the reference as plain text. We write it from the list of calls the API answers, so it never names a call that doesn't exist:

• https://gmaps.dev/llms.txt is where to start: what gmaps.dev is, how the calls fit together, every call in one line, and a link to each guide.
• https://gmaps.dev/llms-full.txt has everything on one page: every call with its fields, what costs credits, and every error code with its HTTP status.
• https://gmaps.dev/docs/reference/search_places.md is one call on its own page: its address, fields, SDK method and tool name. Every call has one, under the call's own name.

The files are in English, like the tool descriptions your agent reads.

A tool runs the same code as its API call, so it costs the same and counts against the same limits:

• 0A place we already saved comes back in the same answer, marked cached: true.
• 1A new place that a collection finds for you.
• 1Emails for a new place, on paid plans: 1 credit per place, only when we find at least one.
• 0Searching, quotes, exports and checking your usage.
• 0A collection that finds nothing.

• Only search_places and create_collection can spend credits. Every other tool is free.
• Your limit on requests per minute counts each tool call, even when your agent sends several in one request.
• A tool's answer has no headers, so there's no x-credits-remaining. To see what's left, the agent calls get_usage.

The tool answers with the same error the API would give: a code, a message that says what to do next, and sometimes details. Errors lists every code. Two to plan for:

• QUOTA_EXCEEDED: no credits left today or this month, or too many collections running at once. details.scope says which: day, month or concurrency. Wait for the limit to reset or a collection to end, or change your plan.
• PLAN_GATE: your plan doesn't include that feature, such as webhooks. details.upgradeTo names the plan that does.

• The server takes POST requests only. It keeps no session and sends no live updates, so your agent follows a collection with get_collection.
• Each tool carries hints for clients that ask you before risky calls. The tools whose API call is a GET are marked read-only, and cancel_collection and delete_webhook are marked destructive.
• In a browser, only our own sites can call the server, so a page on another site can't use it. Agents that don't run in a browser aren't affected.
• A place is not permission to contact anyone. Email addresses come only on paid plans, after your account accepts the acceptable use policy.