Conecta agentes de IA a listingsAPI MCP

Conecta Claude, ChatGPT, Cursor o Gemini al servidor MCP alojado para leer tus ubicaciones, fichas y reseñas y actuar con las mismas herramientas que tú.

La Listings API aloja un servidor Model Context Protocol (MCP) en https://listingsapi.com/mcp. No hay nada que instalar ni ejecutar. Un asistente de IA compatible con MCP se conecta a esa URL, descubre una herramienta por cada endpoint REST y algunas herramientas de documentación, y las invoca en tu cuenta. Esta guía explica cómo conectar cada uno de los principales clientes y verificar después la conexión.

1. Conoce las herramientas disponibles para el agente

El servidor expone algo más de 60 herramientas, de las cuales aproximadamente 2 tercios son de solo lectura. Los nombres corresponden a los recursos REST, por lo que locations_search, listings_premium, reviews_respond y posts_create_social hacen lo mismo que los endpoints correspondientes, con los mismos parámetros y la misma estructura de respuesta. Las 3 herramientas de documentación, search_docs, get_doc y get_endpoint, permiten al asistente consultar una página o el contrato de un endpoint en lugar de adivinar la estructura de los datos que debe enviar.

Las operaciones destructivas, como eliminar una publicación o archivar una ubicación, no se exponen como herramientas. Usa la API REST o un SDK para esas operaciones, de modo que un asistente no pueda eliminar datos por su cuenta.

2. Elige cómo inicia sesión el cliente

Cada cliente se autentica de una de estas dos formas. Ambas utilizan una misma clave de API en el servidor, por lo que los límites de solicitudes y los informes de uso son idénticos.

OAuth utiliza el flujo de código de autorización con PKCE y el registro dinámico de clientes, por lo que un cliente no necesita credenciales emitidas previamente. Los metadatos están en https://listingsapi.com/.well-known/oauth-authorization-server. Los ámbitos son read y write; un cliente que no solicite ninguno recibe read. Cada autorización crea una clave exclusiva para esa conexión, que puedes revocar desde /dashboard/keys como cualquier otra clave.

3. Conecta Claude

Claude.ai y Claude Desktop. El servidor figura en el directorio de conectores, por lo que la forma más rápida es abrir https://claude.ai/directory/listings-api y hacer clic en Connect (conectar). Claude ejecuta el flujo de OAuth, tú autorizas los ámbitos y las herramientas quedan disponibles en cualquier chat en el que actives el conector mediante el botón + y luego Connectors (conectores).

Si prefieres añadirlo mediante su URL, ve a Customize (personalizar), luego a Connectors (conectores), haz clic en + y en Add custom connector (añadir conector personalizado), pega https://listingsapi.com/mcp y haz clic en Add (añadir). Deja Advanced settings (configuración avanzada) vacío; el servidor registra automáticamente a Claude como cliente. En los planes Team y Enterprise, un propietario añade el conector en Organization settings (configuración de la organización) y luego en Connectors (conectores), y después los miembros hacen clic en Connect (conectar) en ese conector. Claude se conecta desde los servidores de Anthropic, no desde tu equipo, por lo que es importante usar la URL del servidor alojado.

Claude Code. Un solo comando añade el servidor con tu clave:

claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

Omite la opción --header y ejecuta /mcp dentro de Claude Code para iniciar sesión a través del navegador. Usa --scope project para guardar la configuración del servidor en un archivo .mcp.json compartido por todo el equipo y añadirlo al repositorio; no incluyas una clave en ese archivo.

4. Conecta ChatGPT

ChatGPT se conecta a servidores MCP remotos mediante un conector personalizado una vez que activas Developer mode (modo de desarrollador). Está disponible en los planes Plus, Pro, Business, Enterprise y Edu, pero no en el plan gratuito.

1. Abre Settings (configuración) desde el menú de tu perfil y activa Developer mode (modo de desarrollador). Según la versión, se encuentra en Apps & Connectors (aplicaciones y conectores) o en Security and login (seguridad e inicio de sesión).
2. En la página de conectores (denominada Plugins (complementos) en las versiones actuales), haz clic en + o en Create (crear).
3. Introduce un nombre, pega https://listingsapi.com/mcp como URL del servidor y elige OAuth para la autenticación. Guarda los cambios.
4. ChatGPT abre la página de inicio de sesión. Aprueba read o read write.
5. En un chat nuevo, abre el menú de herramientas, selecciona el conector y confirma que aparece con sus herramientas. Las herramientas de escritura siguen requiriendo una confirmación.

Codex CLI. El agente de terminal de OpenAI lee los servidores MCP de ~/.codex/config.toml. Codex inicia OAuth automáticamente para los servidores HTTP y respeta los ámbitos anunciados, por lo que la línea de la cabecera es opcional:

[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. Conecta Cursor

La página del panel en /dashboard/mcp tiene un botón Add to Cursor (añadir a Cursor). Este abre un enlace de instalación de Cursor con la URL del servidor y tu clave ya introducidas, por lo que un clic completa la configuración.

Para configurarlo manualmente, añade el servidor a ~/.cursor/mcp.json para todos los proyectos, o a .cursor/mcp.json dentro de un repositorio:

{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

Elimina el bloque headers para iniciar sesión con OAuth: Cursor muestra un botón Connect (conectar) en la entrada del servidor, en Settings (configuración) y luego MCP, y abre el flujo de autenticación en el navegador. Nunca incluyas en un commit una clave dentro de un archivo .cursor/mcp.json del proyecto; usa el archivo global u OAuth para los repositorios compartidos.

6. Conecta Gemini

Gemini CLI. El agente de terminal de Google acepta servidores remotos en ~/.gemini/settings.json (o en .gemini/settings.json dentro de un proyecto). Usa httpUrl, no url, para que seleccione el transporte Streamable HTTP:

{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

Para usar OAuth, sustituye el bloque headers por "oauth": { "enabled": true }, inicia la CLI y ejecuta /mcp auth listingsapi. Ejecuta /mcp en cualquier momento para mostrar el servidor, su estado de conexión y las herramientas que ha descubierto.

Aplicación Gemini. La aplicación Gemini para consumidores no tiene una opción para configurar conectores personalizados. Los servidores MCP personalizados están disponibles para los administradores de equipos de la edición Business de Gemini Enterprise: inicia sesión en business.gemini.google, abre Settings & help (configuración y ayuda), luego Manage team (administrar equipo) y Connected apps (aplicaciones conectadas), y haz clic en Add MCP Server (añadir servidor MCP). Pega https://listingsapi.com/mcp como URL. El formulario solicita los datos de OAuth: la URL de autorización es https://listingsapi.com/oauth/authorize, la URL del token es https://listingsapi.com/oauth/token y los ámbitos son read write. También solicita un ID de cliente y un secreto de cliente. Este servidor emite clientes PKCE públicos sin secreto, así que registra uno con la URL de redirección que muestra el formulario y deja el secreto en blanco si el formulario lo permite:

curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

La respuesta contiene client_id. Si el formulario de Gemini exige un secreto, usa la opción de Gemini CLI descrita arriba o desarrolla con la API de Gemini.

Desarrollo con la API de Gemini. El SDK de la API de Gemini acepta una sesión de cliente MCP como herramienta, por lo que un script puede proporcionar las mismas herramientas a un modelo de Gemini:

import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. Verifica la conexión

Antes de confiar en el asistente, confirma que el servidor te responde directamente. El descubrimiento de herramientas no requiere una clave, por lo que esta llamada funciona con cualquier cliente que pueda acceder a la URL:

curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Después, dentro del asistente, pide algo que requiera acceder a tu cuenta:

Usa las herramientas de listingsapi para mostrar mi plan, contar mis ubicaciones e informar sobre mi uso de la API este mes.

Una conexión que funciona devuelve tu plan y el estado de acceso desde whoami, los datos de las ubicaciones desde locations_all y los recuentos de uso desde get_usage. Una clave incorrecta o caducada provoca un error Unauthenticated en la primera llamada a una herramienta, no durante el descubrimiento.

Primeras instrucciones para el agente que puedes probar cuando funcione:

• "Enumera mis ubicaciones que tengan errores en sus fichas y resume cada error."
• "Muestra las reseñas recibidas en los últimos 7 días que no tengan respuesta y redacta una respuesta para cada una. No las envíes todavía."
• "Compara las estadísticas del perfil de Google de la ubicación 1800289 entre los últimos dos meses."
• "Lee el contrato del endpoint create-location y después añade esta ubicación: ..."

Añade las habilidades de agente de listingsAPI

Las habilidades son instrucciones que un agente carga cuando una tarea coincide con su propósito, para seguir un flujo de trabajo probado en lugar de crear uno. Funcionan junto con el servidor MCP: el servidor realiza las llamadas y la habilidad determina qué llamadas realizar y en qué orden. Hay cinco habilidades de listingsAPI publicadas en skills.sh desde el repositorio público listingsapi-mcp:

Instala las cinco en tu proyecto con la CLI de Skills:

npx skills add listings-api/listingsapi-mcp

O instala una por su nombre y elige el agente con -a:

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

Usa -a cursor o -a codex para esos agentes y añade -g para instalarla para todos los proyectos en lugar de solo para el actual.

Busca listingsAPI en directorios de herramientas de IA

El mismo servidor aparece en estos directorios, junto con la habilidad de agente de listingsAPI. Instálalo desde el directorio que ya use tu cliente. Todas las entradas del servidor MCP apuntan a https://listingsapi.com/mcp.

Solución de problemas

Siguientes pasos

• Elige cómo integrar: cuándo conviene usar MCP y cuándo es mejor usar REST o un SDK.
• Realiza tu primera llamada a la API: obtén una clave y conoce la estructura de las respuestas que devuelven las herramientas.
• Responde a eventos con webhooks: configura la plataforma para que notifique a tu agente en lugar de realizar consultas periódicas.
• Autenticación y Códigos de error para consultar los códigos que te comunicará el asistente.