MCP para agentes

O MCP (Model Context Protocol) é um padrão para agentes de IA usarem ferramentas externas. Conecte o gmaps.dev uma vez e o seu agente passa a encontrar lugares, acompanhar uma coleta e entregar um arquivo para você, sem ajuda.

O endereço é https://api.gmaps.dev/mcp. O agente usa a mesma chave de API do seu código, enviada do mesmo jeito, num cabeçalho Authorization: Bearer. Coloque este bloco nas configurações de MCP dele:

{
  "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 seu agente vê 18 ferramentas. Cada uma é uma chamada da API com outro nome e os mesmos campos:

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.

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.

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ê.

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.

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. Dois para ter em mente:

• 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.

• 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.