Integraciones

MCP para agentes

Conecta tu app de IA para buscar lugares, recopilar una zona y crear exportaciones. Las llamadas usan los créditos y los límites de tu cuenta.

Conecta tu agente

Servidor: https://api.gmaps.dev/mcp. Usa Streamable HTTP. En un cliente compatible con OAuth, agrega esta URL e inicia sesión en gmaps.dev. Después de conectar, prueba esta solicitud:

Encuentra hasta 10 tiendas de bicicletas en Curitiba, PR. Dime cuáles ya estaban guardadas y cuánto costaron los resultados nuevos.

El agente llama a search_places. Los lugares guardados llegan de inmediato y gratis. Si hacen falta más, una recopilación corre en segundo plano y cobra los lugares nuevos, hasta el límite que diste.

En Claude Code, instala el plugin de gmaps desde el marketplace owe-br:

claude plugin marketplace add owe-br/plugins
claude plugin install gmaps@owe-br

Luego escribe /mcp, elige gmaps y selecciona Authenticate.

En Codex, ejecuta:

codex plugin marketplace add owe-br/plugins
codex plugin add gmaps@owe-br
codex mcp login gmaps

La última línea inicia tu sesión. Necesita Codex 0.147 o posterior: las versiones anteriores fallan con "missing required issuer". Para actualizar, ejecuta npm install -g @openai/codex@latest.

En otras apps de IA, agrega https://api.gmaps.dev/mcp como servidor MCP remoto y elige Conectar. En todas, tu navegador abre luego gmaps.dev. Inicia sesión y revisa el nombre de la app y la dirección de retorno antes de aprobar. No hay una clave de API que copiar: la conexión crea una clave normal en tu cuenta, y al revocarla en Claves de API se desconecta la app.

Un agente sin navegador puede pedir un código corto con client_id=gmaps-agent en https://api.gmaps.dev/oauth/device_authorization. Abre el enlace de verificación que recibas y aprueba solo si el código coincide con el del agente que acabas de iniciar. El agente consulta el endpoint de token con el código de dispositivo y el recurso que recibió. El descubrimiento de OAuth lista los endpoints.

La app de IA recibe los resultados de las herramientas. Lee qué recibe y qué guarda gmaps.dev en la política de privacidad. Tu app de IA tiene sus propias reglas para los datos que recibe.

Si tu cliente MCP solo admite claves, agrega este bloque. Mantén la clave fuera de git:

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

En Claude Code, guárdalo como .mcp.json en la raíz de tu proyecto. Claude Code completa ${GMAPS_API_KEY} desde tu entorno, así que el archivo nunca guarda la clave.
En otro cliente, agrega la misma dirección y el mismo encabezado donde guarda sus servidores MCP. Si no completa ${GMAPS_API_KEY} por sí solo, escribe ahí tu clave y mantén ese archivo fuera de git.
Cuando creas una clave en Claves de API, la consola muestra este bloque con esa clave ya puesta.

Lo que permites

La conexión no es de solo lectura. Puede iniciar y cancelar recopilaciones, crear exportaciones y administrar tus webhooks. Las herramientas de búsqueda y recopilación pueden gastar tus créditos. Actúa sobre la cuenta que inició sesión, con el mismo acceso que una clave de API normal. No hay permisos por herramienta. Revisa la solicitud antes de aprobar una llamada que cambia o envía algo.

Para detener nuevas llamadas, revoca la clave con el nombre de la app en Claves de API. Quitar el servidor de tu app de IA no revoca esa clave por sí solo. Las recopilaciones ya iniciadas siguen corriendo; usa cancel_collection para detenerlas. Mantén las claves fuera de los prompts y las URL.

Las herramientas

Tu agente ve 18 herramientas. Cada una es una llamada de la API con otro nombre, con los mismos campos:

Herramienta	Llamada de la API	Qué hace
`search_places`	`POST /v1/places/search`	Encuentra lugares por lo que son y dónde están. Responde de inmediato con los lugares que tenemos guardados.
`get_place`	`GET /v1/places/{place}`	Lee un lugar que tenemos guardado. Nunca busca.
`get_collection`	`GET /v1/collections/{id}`	Muestra cuánto ha avanzado una recopilación y cuánto ha costado.
`list_collections`	`GET /v1/collections`	Tus recopilaciones, de la más nueva a la más antigua.
`quote_collection`	`POST /v1/collections/quote`	Muestra lo máximo que costaría una recopilación, sin iniciarla.
`create_collection`	`POST /v1/collections`	Busca en una zona completa, cuadro por cuadro, hasta `maxPlaces` lugares.
`cancel_collection`	`DELETE /v1/collections/{id}`	Detiene una recopilación. Te quedas con los lugares que ya llegaron, y los créditos que costaron no se devuelven.
`get_coverage`	`POST /v1/coverage`	Muestra cuánto de una zona ya hemos buscado.
`create_export`	`POST /v1/exports`	Genera un enlace con los lugares de una recopilación como archivo csv, json o xlsx.
`get_export`	`GET /v1/exports/{id}`	Vuelve a leer una exportación mientras su enlace aún funciona.
`get_usage`	`GET /v1/usage`	Créditos usados y restantes, hoy y este mes.
`create_webhook`	`POST /v1/webhooks`	Agrega un endpoint al que llamamos cuando termina una recopilación.
`list_webhooks`	`GET /v1/webhooks`	Tus endpoints de webhook, y si cada uno está activo.
`update_webhook`	`POST /v1/webhooks/{id}`	Cambia los eventos o la nota de un endpoint, o lo apaga y lo enciende.
`test_webhook`	`POST /v1/webhooks/{id}/test`	Envía un evento de prueba a un endpoint.
`list_webhook_deliveries`	`GET /v1/webhooks/{id}/deliveries`	Lo que enviamos a un endpoint y lo que respondió.
`delete_webhook`	`DELETE /v1/webhooks/{id}`	Elimina un endpoint y su registro de entregas.
`get_attributions`	`GET /v1/attributions`	Los proyectos de código abierto en los que nos apoyamos. No necesita clave.

Una llamada de la API no tiene herramienta: GET /v1/collections/{id}/places. Una página de lugares completos llenaría el contexto de tu agente, el texto que puede retener a la vez. Por eso lee los lugares con search_places y te entrega muchos de ellos como una exportación.

Las herramientas de webhook necesitan un plan de pago. get_attributions no necesita clave, y pedir la lista de herramientas tampoco.

Cómo encajan las herramientas

El servidor envía estos pasos a tu agente cuando se conecta. Están aquí para que sepas qué va a hacer:

Empieza con search_places: qué buscar y una zona. Eso responde de inmediato y gratis, con los lugares que tenemos guardados. Si no llegan a limit, empieza una recopilación para encontrar el resto.
Una recopilación tarda unos minutos. El agente la revisa con get_collection y luego repite la misma búsqueda. Los lugares nuevos vuelven, y esta vez son gratis.
Para una ciudad completa, primero ejecuta quote_collection. Es gratis y dice lo máximo que puede costar la recopilación. Luego llama a create_collection con maxPlaces.
Para entregarte los lugares, crea una exportación con create_export y te da el enlace. El enlace abre un archivo csv, json o xlsx durante 24 horas, y los lugares nunca pasan por el contexto del agente.
get_place lee un lugar que tenemos guardado, por nuestro id, su cid, su place ID o un enlace de Maps. Nunca busca.
get_usage muestra los créditos que quedan hoy y este mes. create_webhook avisa a tu servidor cuando termina una recopilación, así nadie tiene que estar revisando.

Documentación para agentes que leen

Algunos agentes leen documentación en lugar de llamar herramientas. Para ellos publicamos la referencia como texto plano. La escribimos a partir de la lista de llamadas que responde la API, así que nunca nombra una llamada que no existe:

https://gmaps.dev/llms.txt es el punto de partida: qué es gmaps.dev, cómo encajan las llamadas, cada llamada en una línea y un enlace a cada guía.
https://gmaps.dev/llms-full.txt tiene todo en una sola página: cada llamada con sus campos, qué cuesta créditos y cada código de error con su estado HTTP.
https://gmaps.dev/docs/reference/search_places.md es una llamada en su propia página: su dirección, sus campos, el método del SDK y el nombre de la herramienta. Cada llamada tiene una, con el nombre de la propia llamada.

Los archivos están en inglés, igual que las descripciones de las herramientas que lee tu agente.

Cuánto cuesta

Una herramienta ejecuta el mismo código que su llamada de la API, así que cuesta lo mismo y cuenta para los mismos límites:

0Un lugar que ya guardamos llega en la misma respuesta, marcado con cached: true.
1Un lugar nuevo que encuentra una recopilación para ti.
1Correos electrónicos de un lugar nuevo, en los planes de pago: 1 crédito por lugar, solo cuando encontramos al menos uno.
0Búsquedas, estimaciones, exportaciones y consultar tu uso.
0Una recopilación que no encuentra nada.

Solo search_places y create_collection pueden gastar créditos. Todas las demás herramientas son gratis.
Tu límite de solicitudes por minuto cuenta cada llamada a una herramienta, aunque tu agente envíe varias en una sola solicitud.
La respuesta de una herramienta no tiene encabezados, así que no hay x-credits-remaining. Para ver cuánto queda, el agente llama a get_usage.

Cuando una herramienta falla

La herramienta responde con el mismo error que daría la API: un code, un message que dice qué hacer después, y a veces details. Errores lista todos los códigos. Casos comunes:

Un 401 significa que la llamada no tiene una clave que funcione. Inicia sesión de nuevo o cambia la clave en el cliente. Si la aprobación dice que tienes demasiadas claves, revoca una que no uses en Claves de API y vuelve a conectar.
QUOTA_EXCEEDED: no quedan créditos hoy o este mes, o hay demasiadas recopilaciones en curso a la vez. details.scope dice cuál: day, month o concurrency. Espera a que se reinicie el límite o a que termine una recopilación, o cambia de plan.
PLAN_GATE: tu plan no incluye esa función, como los webhooks. details.upgradeTo indica qué plan sí la incluye.

Conviene saber

El servidor solo acepta solicitudes POST. No guarda sesión ni envía actualizaciones en vivo, así que tu agente sigue una recopilación con get_collection.
Cada herramienta lleva indicaciones para los clientes que te preguntan antes de las llamadas riesgosas. Las herramientas cuya llamada de la API es un GET se marcan como de solo lectura, y cancel_collection y delete_webhook se marcan como destructivas.
En un navegador, solo nuestros propios sitios pueden llamar al servidor, así que una página de otro sitio no puede usarlo. Los agentes que no corren en un navegador no se ven afectados.
Un lugar no es un permiso para contactar a nadie. Los correos electrónicos llegan solo en los planes de pago, después de que tu cuenta acepta la política de uso aceptable.