Integrações
MCP para agentes
Conecte seu aplicativo de IA para buscar lugares, coletar uma região e criar exportações. As chamadas usam os créditos e limites da sua conta.
Conecte o seu agente
Servidor: https://api.gmaps.dev/mcp. Use Streamable HTTP. Num cliente com OAuth, adicione essa URL e entre no gmaps.dev. Depois de conectar, experimente este pedido:
Busque até 10 bicicletarias em Curitiba, PR. Diga quais resultados já estavam salvos e quanto custaram os novos.O agente chama search_places. Os lugares já salvos chegam na hora, de graça. Se faltarem resultados, uma coleta roda em segundo plano e cobra pelos lugares novos, até o limite que você pediu.
No Claude Code, instale o plugin do gmaps pelo marketplace owe-br:
claude plugin marketplace add owe-br/plugins
claude plugin install gmaps@owe-brDepois digite /mcp, escolha gmaps e clique em Authenticate.
No Codex, rode:
codex plugin marketplace add owe-br/plugins
codex plugin add gmaps@owe-br
codex mcp login gmapsA última linha faz o login. Ela precisa do Codex 0.147 ou mais novo: as versões antigas falham com "missing required issuer". Para atualizar, rode npm install -g @openai/codex@latest.
Em outros aplicativos de IA, adicione https://api.gmaps.dev/mcp como servidor MCP remoto e escolha Conectar. Em qualquer aplicativo, o navegador abre o gmaps.dev em seguida. Entre e confira o nome do aplicativo e o endereço de retorno antes de aprovar. Não precisa copiar chave: a conexão cria uma chave comum na sua conta, e revogar essa chave em Chaves de API desconecta o aplicativo.
Um agente sem navegador pode pedir um código curto com client_id=gmaps-agent em https://api.gmaps.dev/oauth/device_authorization. Abra o link de verificação recebido e aprove apenas se o código confere com o do agente que você acabou de iniciar. O agente consulta o endpoint de token com o código de dispositivo e o recurso recebidos. Os documentos de descoberta OAuth listam os endpoints.
O aplicativo de IA recebe os resultados das ferramentas. A política de privacidade explica o que o gmaps.dev recebe e guarda. O aplicativo de IA tem suas próprias regras para os dados que recebe.
Se o seu cliente MCP só aceita chaves, use este bloco. Não salve a chave no git:
{
"mcpServers": {
"gmaps.dev": {
"type": "http",
"url": "https://api.gmaps.dev/mcp",
"headers": { "Authorization": "Bearer ${GMAPS_API_KEY}" }
}
}
}- No Claude Code, salve como
.mcp.jsonna raiz do projeto. O Claude Code troca${GMAPS_API_KEY}pelo valor da variável de ambiente, então a chave nunca fica no arquivo. - Em outro cliente, coloque o mesmo endereço e o mesmo cabeçalho onde ele guarda os servidores MCP. Se ele não trocar
${GMAPS_API_KEY}sozinho, escreva a sua chave no lugar e deixe esse arquivo fora do git. - Quando você cria uma chave em Chaves de API, o console mostra este bloco com a chave já preenchida.
O que você autoriza
A conexão não é só de leitura. Ela pode iniciar e cancelar coletas, criar exportações e gerenciar seus webhooks. As ferramentas de busca e coleta podem gastar seus créditos. Tudo acontece na conta que fez login, com o mesmo acesso de uma chave de API comum. Não há permissão separada por ferramenta. Confira o pedido antes de aprovar uma chamada que muda ou envia algo.
Para impedir novas chamadas, revogue a chave com o nome do app em Chaves de API. Só remover o servidor do app de IA não revoga a chave. Coletas já iniciadas continuam rodando; use cancel_collection para parar. Não coloque chaves em prompts nem URLs.
As ferramentas
O seu agente vê 18 ferramentas. Cada uma é uma chamada da API com outro nome e os mesmos campos:
| Ferramenta | Chamada da API | Para que serve |
|---|---|---|
search_places | POST /v1/places/search | Encontra lugares pelo que são e onde ficam. Responde na hora com os lugares que já salvamos. |
get_place | GET /v1/places/{place} | Lê um lugar que já salvamos. Nunca faz uma busca. |
get_collection | GET /v1/collections/{id} | Mostra até onde a coleta chegou e quanto já custou. |
list_collections | GET /v1/collections | As suas coletas, das mais novas para as mais antigas. |
quote_collection | POST /v1/collections/quote | Mostra o máximo que uma coleta custaria, sem começar nada. |
create_collection | POST /v1/collections | Busca numa região inteira, quadrado por quadrado, até maxPlaces lugares. |
cancel_collection | DELETE /v1/collections/{id} | Para uma coleta. Os lugares que já chegaram continuam seus, e os créditos gastos com eles não voltam. |
get_coverage | POST /v1/coverage | Mostra quanto de uma região já buscamos. |
create_export | POST /v1/exports | Gera um link com os lugares de uma coleta em csv, json ou xlsx. |
get_export | GET /v1/exports/{id} | Lê uma exportação de novo, enquanto o link ainda funciona. |
get_usage | GET /v1/usage | Créditos usados e restantes, no dia e no mês. |
create_webhook | POST /v1/webhooks | Adiciona um endpoint que chamamos quando uma coleta termina. |
list_webhooks | GET /v1/webhooks | Os seus endpoints de webhook, e se cada um está ligado. |
update_webhook | POST /v1/webhooks/{id} | Muda os eventos ou a anotação de um endpoint, ou desliga e liga. |
test_webhook | POST /v1/webhooks/{id}/test | Manda um evento de teste para um endpoint. |
list_webhook_deliveries | GET /v1/webhooks/{id}/deliveries | O que mandamos para um endpoint e o que ele respondeu. |
delete_webhook | DELETE /v1/webhooks/{id} | Remove um endpoint e o histórico de entregas dele. |
get_attributions | GET /v1/attributions | Os projetos de código aberto que usamos. Não precisa de chave. |
Uma chamada da API ficou sem ferramenta: GET /v1/collections/{id}/places. Uma página de lugares completos lotaria o contexto do agente, que é o texto que ele consegue guardar de uma vez. Por isso ele lê os lugares com search_places e, quando são muitos, entrega uma exportação.
As ferramentas de webhook precisam de um plano pago. O get_attributions não precisa de chave, e pedir a lista de ferramentas também não.
Como as ferramentas se encaixam
O servidor manda estes passos para o agente quando ele se conecta. Eles estão aqui para você saber o que ele vai fazer:
- Ele começa com
search_places: o que procurar e uma região. A resposta vem na hora, de graça, com os lugares que já salvamos. Se eles não chegarem aolimit, uma coleta começa a buscar o resto. - Uma coleta leva alguns minutos. O agente confere com
get_collectione depois faz a mesma busca de novo. Os lugares novos voltam, e dessa vez de graça. - Para uma cidade inteira, ele roda
quote_collectionantes. É de graça e mostra o máximo que a coleta pode custar. Depois chamacreate_collectioncommaxPlaces. - Para entregar os lugares a você, ele gera uma exportação com
create_exporte passa o link. O link abre um arquivo csv, json ou xlsx por 24 horas, e os lugares nem passam pelo contexto do agente. get_placelê um lugar que já salvamos, pelo nosso id, pelo cid, pelo place ID ou por um link do Maps. Nunca faz uma busca.get_usagemostra os créditos que restam no dia e no mês.create_webhookavisa o seu servidor quando uma coleta termina, e ninguém precisa ficar conferindo.
Documentação para agentes que leem
Alguns agentes leem a documentação em vez de chamar ferramentas. Para eles, publicamos a referência em texto puro. Ela sai da mesma lista de chamadas que a API atende, então nunca cita uma chamada que não existe:
https://gmaps.dev/llms.txté o ponto de partida: o que é o gmaps.dev, como as chamadas se encaixam, cada chamada numa linha e um link para cada guia.https://gmaps.dev/llms-full.txttraz tudo numa página só: cada chamada com os campos dela, o que gasta créditos e cada código de erro com o status HTTP.https://gmaps.dev/docs/reference/search_places.mdtraz uma chamada por página: endereço, campos, método do SDK e nome da ferramenta. Toda chamada tem a sua, com o nome da própria chamada.
Os arquivos são em inglês, como as descrições das ferramentas que o agente lê.
Quanto custa
Uma ferramenta roda o mesmo código da chamada da API, então custa o mesmo e conta nos mesmos limites:
- 0Um lugar que já salvamos volta na mesma resposta, marcado com
cached: true. - 1Um lugar novo que uma coleta encontra para você.
- 1E-mails de um lugar novo, nos planos pagos: 1 crédito por lugar, só quando encontramos pelo menos um.
- 0Buscas, estimativas, exportações e consultas ao seu consumo.
- 0Uma coleta que não encontra nada.
- Só
search_placesecreate_collectiongastam créditos. Todas as outras ferramentas são de graça. - O seu limite de requisições por minuto conta cada chamada de ferramenta, mesmo quando o agente manda várias numa requisição só.
- A resposta de uma ferramenta não tem cabeçalhos, então não vem o
x-credits-remaining. Para ver quanto sobrou, o agente chamaget_usage.
Quando uma ferramenta falha
A ferramenta responde com o mesmo erro que a API daria: um code, uma message que diz o que fazer, e às vezes details. Erros lista todos os códigos. Alguns casos comuns:
- Um 401 indica que a chamada está sem uma chave válida. Entre de novo ou troque a chave no cliente. Se a autorização avisar que há chaves demais, revogue uma que não usa em Chaves de API e conecte de novo.
QUOTA_EXCEEDED: os créditos do dia ou do mês acabaram, ou há coletas demais rodando ao mesmo tempo. Odetails.scopediz qual:day,monthouconcurrency. Espere o limite renovar ou uma coleta terminar, ou mude de plano.PLAN_GATE: o seu plano não inclui esse recurso, como os webhooks. Odetails.upgradeTodiz qual plano inclui.
Bom saber
- O servidor só aceita requisições POST. Ele não guarda sessão nem manda atualizações ao vivo, então o agente acompanha uma coleta com
get_collection. - Cada ferramenta traz dicas para clientes que pedem confirmação antes de ações arriscadas. As ferramentas cuja chamada da API é um GET vêm marcadas como somente leitura, e
cancel_collectionedelete_webhookvêm marcadas como destrutivas. - No navegador, só os nossos próprios sites conseguem chamar o servidor, então uma página de outro site não consegue usá-lo. Agentes que não rodam num navegador não são afetados.
- Um lugar não é autorização para entrar em contato com ninguém. Endereços de e-mail só vêm nos planos pagos, depois que a sua conta aceita a política de uso aceitável.