Pular para o conteúdo

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-br

Depois 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 gmaps

A ú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.json na 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:

FerramentaChamada da APIPara que serve
search_placesPOST /v1/places/searchEncontra lugares pelo que são e onde ficam. Responde na hora com os lugares que já salvamos.
get_placeGET /v1/places/{place}Lê um lugar que já salvamos. Nunca faz uma busca.
get_collectionGET /v1/collections/{id}Mostra até onde a coleta chegou e quanto já custou.
list_collectionsGET /v1/collectionsAs suas coletas, das mais novas para as mais antigas.
quote_collectionPOST /v1/collections/quoteMostra o máximo que uma coleta custaria, sem começar nada.
create_collectionPOST /v1/collectionsBusca numa região inteira, quadrado por quadrado, até maxPlaces lugares.
cancel_collectionDELETE /v1/collections/{id}Para uma coleta. Os lugares que já chegaram continuam seus, e os créditos gastos com eles não voltam.
get_coveragePOST /v1/coverageMostra quanto de uma região já buscamos.
create_exportPOST /v1/exportsGera um link com os lugares de uma coleta em csv, json ou xlsx.
get_exportGET /v1/exports/{id}Lê uma exportação de novo, enquanto o link ainda funciona.
get_usageGET /v1/usageCréditos usados e restantes, no dia e no mês.
create_webhookPOST /v1/webhooksAdiciona um endpoint que chamamos quando uma coleta termina.
list_webhooksGET /v1/webhooksOs seus endpoints de webhook, e se cada um está ligado.
update_webhookPOST /v1/webhooks/{id}Muda os eventos ou a anotação de um endpoint, ou desliga e liga.
test_webhookPOST /v1/webhooks/{id}/testManda um evento de teste para um endpoint.
list_webhook_deliveriesGET /v1/webhooks/{id}/deliveriesO que mandamos para um endpoint e o que ele respondeu.
delete_webhookDELETE /v1/webhooks/{id}Remove um endpoint e o histórico de entregas dele.
get_attributionsGET /v1/attributionsOs 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:

  1. 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 ao limit, uma coleta começa a buscar o resto.
  2. Uma coleta leva alguns minutos. O agente confere com get_collection e depois faz a mesma busca de novo. Os lugares novos voltam, e dessa vez de graça.
  3. Para uma cidade inteira, ele roda quote_collection antes. É de graça e mostra o máximo que a coleta pode custar. Depois chama create_collection com maxPlaces.
  4. Para entregar os lugares a você, ele gera uma exportação com create_export e passa o link. O link abre um arquivo csv, json ou xlsx por 24 horas, e os lugares nem passam pelo contexto do agente.
  5. get_place lê um lugar que já salvamos, pelo nosso id, pelo cid, pelo place ID ou por um link do Maps. Nunca faz uma busca.
  6. get_usage mostra os créditos que restam no dia e no mês. create_webhook avisa 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.txt traz 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.md traz 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_places e create_collection gastam 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 chama get_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. O details.scope diz qual: day, month ou concurrency. 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. O details.upgradeTo diz 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_collection e delete_webhook vê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.