Integrations
MCP for agents
Connect your AI app to search for places, collect an area and create exports. Calls use your account credits and limits.
Connect your agent
Server: https://api.gmaps.dev/mcp. Use Streamable HTTP. In an OAuth-capable client, add this URL and sign in to gmaps.dev. After connecting, try this request:
Find up to 10 bike shops in Curitiba, PR. Tell me what was already saved and what the new results cost.The agent calls search_places. Saved places arrive at once for free. If more are needed, a collection runs in the background and charges for new places, up to the limit you gave.
In Claude Code, install the gmaps plugin from the owe-br marketplace:
claude plugin marketplace add owe-br/plugins
claude plugin install gmaps@owe-brThen type /mcp, pick gmaps and choose Authenticate.
In Codex, run:
codex plugin marketplace add owe-br/plugins
codex plugin add gmaps@owe-br
codex mcp login gmapsThe last line signs you in. It needs Codex 0.147 or later: older versions fail with "missing required issuer". To update, run npm install -g @openai/codex@latest.
In other AI apps, add https://api.gmaps.dev/mcp as a remote MCP server and choose Connect. In every app, your browser then opens gmaps.dev. Sign in and check the app name and return address before you approve. There's no API key to copy: the connection creates a normal key on your account, and revoking it under API keys disconnects the app.
An agent without a browser can request a short code with client_id=gmaps-agent at https://api.gmaps.dev/oauth/device_authorization. Open the returned verification link and approve only if the code matches the agent you just started. The agent polls the token endpoint with the returned device code and resource. OAuth discovery lists the endpoints.
The AI app receives the tool results. Read what gmaps.dev receives and keeps in the privacy policy. Your AI app has its own rules for the data it receives.
If your MCP client only supports keys, add this block instead. Keep the key out of git:
{
"mcpServers": {
"gmaps.dev": {
"type": "http",
"url": "https://api.gmaps.dev/mcp",
"headers": { "Authorization": "Bearer ${GMAPS_API_KEY}" }
}
}
}- In Claude Code, save it as
.mcp.jsonat 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.
What you allow
The connection is not read-only. It can start and cancel collections, create exports and manage your webhooks. Search and collection tools can spend your credits. It acts on the account that signed in, with the same access as a normal API key. There are no per-tool permissions. Review the request before you approve a call that changes or sends something.
To stop new calls, revoke the app's named key under API keys. Removing the server from your AI app alone does not revoke that key. Collections already started keep running; use cancel_collection to stop them. Keep keys out of prompts and URLs.
The tools
Your agent sees 18 tools. Each one is an API call under another name, with the same fields:
| Tool | API call | What it does |
|---|---|---|
search_places | POST /v1/places/search | Find places by what they are and where they are. Answers at once with the places we have saved. |
get_place | GET /v1/places/{place} | Read one place we have saved. It never searches. |
get_collection | GET /v1/collections/{id} | See how far a collection has got and what it has cost. |
list_collections | GET /v1/collections | Your collections, newest first. |
quote_collection | POST /v1/collections/quote | See the most a collection would cost, without starting it. |
create_collection | POST /v1/collections | Search a whole area, square by square, up to maxPlaces places. |
cancel_collection | DELETE /v1/collections/{id} | Stop a collection. You keep the places that already arrived, and the credits they cost stay spent. |
get_coverage | POST /v1/coverage | See how much of an area we have searched. |
create_export | POST /v1/exports | Get a link to a collection's places as a csv, json or xlsx file. |
get_export | GET /v1/exports/{id} | Read an export again while its link still works. |
get_usage | GET /v1/usage | Credits used and left, today and this month. |
create_webhook | POST /v1/webhooks | Add an endpoint that we call when a collection ends. |
list_webhooks | GET /v1/webhooks | Your webhook endpoints, and whether each one is on. |
update_webhook | POST /v1/webhooks/{id} | Change an endpoint's events or note, or turn it off and on. |
test_webhook | POST /v1/webhooks/{id}/test | Send a test event to an endpoint. |
list_webhook_deliveries | GET /v1/webhooks/{id}/deliveries | What we sent to an endpoint and what it answered. |
delete_webhook | DELETE /v1/webhooks/{id} | Remove an endpoint and its delivery log. |
get_attributions | GET /v1/attributions | The open-source projects we build on. Needs no key. |
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.
How the tools fit together
The server sends these steps to your agent when it connects. They're here so you know what it will do:
- 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 filllimit, a collection starts to find the rest. - 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. - For a whole city, it runs
quote_collectionfirst. That's free and says the most the collection can cost. Then it callscreate_collectionwithmaxPlaces. - To hand places to you, it makes an export with
create_exportand 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. get_placereads one place we have saved, by our id, its cid, its place ID or a Maps link. It never searches.get_usageshows the credits left today and this month.create_webhooktells your server when a collection ends, so nothing has to keep checking.
Docs for agents that read
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.txtis 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.txthas 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.mdis 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.
What it costs
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_placesandcreate_collectioncan 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 callsget_usage.
When a tool fails
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. Common cases:
- A 401 means the call has no working key. Sign in again or replace the key in the client. If approval says you have too many keys, revoke an unused one under API keys and reconnect.
QUOTA_EXCEEDED: no credits left today or this month, or too many collections running at once.details.scopesays which:day,monthorconcurrency. 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.upgradeTonames the plan that does.
Good to know
- 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_collectionanddelete_webhookare 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.