Conecta un agente de IA con MCP

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

Listings API aloja un servidor de 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, además de 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 después verificar la conexión.

1. Conoce las herramientas disponibles para el agente

El servidor expone algo más de 60 herramientas, de las cuales aproximadamente dos 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. Tres 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 dos formas. Ambas se traducen en la misma clave de API en el servidor, por lo que los límites de solicitudes y los informes de uso son idénticos.

OAuth usa 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 solicita ninguno recibe read. Cada aprobació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 aparece 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ú apruebas los ámbitos y las herramientas están disponibles en cualquier chat en el que actives el conector mediante el botón + y después Connectors (Conectores).

Si prefieres añadirlo mediante una URL, ve a Customize (Personalizar), después 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 Claude como cliente automáticamente. En los planes Team y Enterprise, un propietario añade el conector en Organization settings (Configuración de la organización) y después en Connectors (Conectores), y los miembros hacen clic en Connect (Conectar) en ese conector a continuación. Claude se conecta desde los servidores de Anthropic, no desde tu equipo, por eso es importante la URL alojada.

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 en su lugar. Usa --scope project para guardar en el control de versiones la configuración del servidor en un archivo .mcp.json compartido por todo el equipo; no incluyas ninguna clave al hacerlo.

4. Conecta ChatGPT

ChatGPT se conecta a servidores MCP remotos mediante un conector personalizado una vez que se activa 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 por su cuenta 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 rellenadas, por lo que basta un clic para completar 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 en su lugar: Cursor muestra un botón Connect (conectar) en la entrada del servidor, dentro de Settings (configuración) y luego MCP, y abre el flujo en el navegador. Nunca incluyas una clave en un commit dentro de un archivo .cursor/mcp.json a nivel de 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 ver 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 de configuración de 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 (gestionar 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 tu formulario de Gemini exige un secreto, usa la opción de Gemini CLI descrita anteriormente o desarrolla con la API de Gemini en su lugar.

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 se completa correctamente 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, solicita algo que requiera acceder a tu cuenta:

Usa las herramientas de listingsapi para decirme con qué cuenta estoy conectado, cuántas ubicaciones tiene y cuál es mi uso de la API este mes.

Una conexión correcta responde a partir de whoami, locations_all y get_usage con el id real de tu cuenta y los recuentos reales. Una clave incorrecta o caducada da lugar a un error Unauthenticated en la primera llamada a una herramienta, no durante el descubrimiento.

Estas son algunas buenas instrucciones para el agente con las que empezar una vez que funcione:

• "Enumera mis ubicaciones que tengan errores en las 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 analíticas del perfil de Google de la ubicación 1800289 entre los últimos dos meses."
• "Lee el contrato del endpoint create-location y luego añade esta ubicación: ..."

Añade las habilidades de listingsAPI para agentes

Las habilidades son instrucciones que un agente carga cuando una tarea coincide con su ámbito, para seguir un flujo de trabajo probado en lugar de idear uno. Funcionan junto con el servidor MCP: el servidor realiza las llamadas y la habilidad decide cuáles 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 en todos los proyectos en lugar de solo en el actual.

Encuentra listingsAPI en directorios de herramientas de IA

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

Solución de problemas

Próximos pasos

• Elige cómo integrar: cuándo conviene MCP y cuándo REST o un SDK es la mejor opción.
• Realiza tu primera llamada a la API: obtén una clave y conoce la estructura de las respuestas que devuelven las herramientas.
• Reacciona a eventos con webhooks: haz que la plataforma 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.