Connectez des agents IA à listingsAPI MCP

Reliez Claude, ChatGPT, Cursor ou Gemini au serveur MCP hébergé pour lire et gérer vos établissements, fiches et avis avec les mêmes outils que vous.

La Listings API héberge un serveur Model Context Protocol (MCP) à l’adresse https://listingsapi.com/mcp. Vous n’avez rien à installer ni à exécuter. Un assistant IA compatible avec MCP se connecte à cette URL, découvre un outil par point de terminaison REST ainsi que quelques outils de documentation, puis les appelle sur votre compte. Ce guide explique comment connecter chaque client principal, puis vérifier la connexion.

1. Comprendre ce à quoi l’agent a accès

Le serveur expose un peu plus de 60 outils, dont environ les deux tiers sont en lecture seule. Leurs noms correspondent aux ressources REST : locations_search, listings_premium, reviews_respond et posts_create_social effectuent donc les mêmes opérations que les points de terminaison correspondants, avec les mêmes paramètres et la même structure de réponse. Trois outils de documentation, search_docs, get_doc et get_endpoint, permettent à l’assistant de consulter une page ou le contrat d’un point de terminaison au lieu de deviner la structure des données à envoyer.

Les opérations destructives, comme la suppression d’une publication ou l’archivage d’un établissement, ne sont pas exposées sous forme d’outils. Utilisez l’API REST ou un SDK pour ces opérations, afin qu’un assistant ne puisse pas supprimer des données de sa propre initiative.

2. Choisir le mode de connexion du client

Chaque client s’authentifie selon l’une des deux méthodes suivantes. Les deux reposent au final sur le même mécanisme de clé API côté serveur ; les limites de débit et les rapports d’utilisation sont donc identiques.

OAuth utilise le flux de code d’autorisation avec PKCE et l’enregistrement dynamique des clients ; un client n’a donc pas besoin d’identifiants émis à l’avance. Les métadonnées sont disponibles à l’adresse https://listingsapi.com/.well-known/oauth-authorization-server. Les portées sont read et write ; un client qui n’en demande aucune obtient read. Chaque approbation crée une clé dédiée à cette connexion, que vous pouvez révoquer depuis /dashboard/keys comme toute autre clé.

3. Connecter Claude

Claude.ai et Claude Desktop. Le serveur figure dans le répertoire des connecteurs ; le plus rapide est donc d’ouvrir https://claude.ai/directory/listings-api et de cliquer sur Connect (Connecter). Claude lance le flux OAuth, vous approuvez les portées, et les outils deviennent disponibles dans toute conversation où vous activez le connecteur à l’aide du bouton +, puis de Connectors (Connecteurs).

Si vous préférez l’ajouter par URL, accédez à Customize (Personnaliser), puis à Connectors (Connecteurs), cliquez sur + et sur Add custom connector (Ajouter un connecteur personnalisé), collez https://listingsapi.com/mcp et cliquez sur Add (Ajouter). Laissez Advanced settings (Paramètres avancés) vide ; le serveur enregistre automatiquement Claude comme client. Avec les forfaits Team et Enterprise, un propriétaire ajoute le connecteur dans Organization settings (Paramètres de l’organisation), puis dans Connectors (Connecteurs), et les membres cliquent ensuite sur Connect (Connecter) pour ce connecteur. Claude se connecte depuis les serveurs d’Anthropic, et non depuis votre machine, d’où l’importance d’utiliser l’URL hébergée.

Claude Code. Une seule commande ajoute le serveur avec votre clé :

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

Pour vous connecter via le navigateur, omettez l’option --header et exécutez /mcp dans Claude Code. Utilisez --scope project pour enregistrer la configuration du serveur dans un fichier .mcp.json partagé par toute l’équipe et l’ajouter au dépôt ; n’y ajoutez pas de clé.

4. Connecter ChatGPT

ChatGPT se connecte à des serveurs MCP distants via un connecteur personnalisé une fois Developer mode (mode développeur) activé. Cette fonctionnalité est disponible avec les forfaits Plus, Pro, Business, Enterprise et Edu, mais pas avec l'offre gratuite.

1. Ouvrez Settings (paramètres) depuis le menu de votre profil et activez Developer mode (mode développeur). Selon la version, cette option se trouve sous Apps & Connectors (applications et connecteurs) ou Security and login (sécurité et connexion).
2. Sur la page des connecteurs (intitulée Plugins (extensions) dans les versions actuelles), cliquez sur + ou Create (créer).
3. Saisissez un nom, collez https://listingsapi.com/mcp comme URL du serveur et choisissez OAuth pour l'authentification. Enregistrez.
4. ChatGPT ouvre la page de connexion. Approuvez read ou read write.
5. Dans une nouvelle conversation, ouvrez le menu des outils, sélectionnez le connecteur et vérifiez qu'il apparaît avec ses outils. Les outils d'écriture restent soumis à une demande de confirmation.

Codex CLI. L'agent en ligne de commande d'OpenAI lit la configuration des serveurs MCP dans ~/.codex/config.toml. Codex lance automatiquement OAuth pour les serveurs HTTP et respecte les portées annoncées ; la ligne d'en-tête est donc facultative :

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

5. Connecter Cursor

La page du tableau de bord à l'adresse /dashboard/mcp comporte un bouton Add to Cursor (ajouter à Cursor). Il ouvre un lien d'installation de Cursor avec l'URL du serveur et votre clé déjà renseignées ; un clic suffit donc à terminer la configuration.

Pour le configurer manuellement, ajoutez le serveur dans ~/.cursor/mcp.json pour tous les projets, ou dans .cursor/mcp.json au sein d'un seul dépôt :

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

Supprimez le bloc headers pour vous connecter avec OAuth à la place : Cursor affiche un bouton Connect (connecter) sur l'entrée du serveur sous Settings (paramètres), puis MCP, et ouvre la procédure d'authentification dans le navigateur. N'enregistrez jamais de clé dans un fichier .cursor/mcp.json propre au projet suivi par le contrôle de version ; utilisez le fichier global ou OAuth pour les dépôts partagés.

6. Connecter Gemini

Gemini CLI. L'agent en ligne de commande de Google lit la configuration des serveurs distants dans ~/.gemini/settings.json (ou .gemini/settings.json dans un projet). Utilisez httpUrl, et non url, pour qu'il sélectionne le transport Streamable HTTP :

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

Pour OAuth, remplacez le bloc headers par "oauth": { "enabled": true }, démarrez l'interface en ligne de commande et exécutez /mcp auth listingsapi. Exécutez /mcp à tout moment pour afficher le serveur, son état de connexion et les outils qu'il a découverts.

Application Gemini. L'application Gemini grand public ne propose aucun paramètre de connecteur personnalisé. Les serveurs MCP personnalisés sont accessibles aux administrateurs d'équipe de l'édition Business de Gemini Enterprise : connectez-vous à business.gemini.google, ouvrez Settings & help (paramètres et aide), puis Manage team (gérer l'équipe) et Connected apps (applications connectées), et cliquez sur Add MCP Server (ajouter un serveur MCP). Collez https://listingsapi.com/mcp comme URL. Le formulaire demande les paramètres OAuth : l'URL d'autorisation est https://listingsapi.com/oauth/authorize, l'URL de jeton est https://listingsapi.com/oauth/token et les portées sont read write. Il demande également un identifiant client et un secret client. Ce serveur crée des clients publics PKCE sans secret ; enregistrez-en donc un avec l'URL de redirection affichée dans le formulaire et laissez le champ du secret vide si le formulaire le permet :

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 réponse contient client_id. Si votre formulaire Gemini exige un secret, utilisez la procédure Gemini CLI ci-dessus ou développez votre intégration avec l'API Gemini à la place.

Développer avec l'API Gemini. Le SDK de l'API Gemini accepte une session client MCP comme outil ; un script peut donc fournir les mêmes outils à un modèle 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. Vérifier la connexion

Avant de vous fier à l'assistant, vérifiez que le serveur vous répond directement. La découverte des outils ne nécessite aucune clé ; cet appel réussit donc avec tout client pouvant accéder à l'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

Ensuite, dans l'assistant, faites une demande qui nécessite un accès à votre compte :

Utilisez les outils listingsapi pour afficher mon forfait, compter mes établissements et indiquer mon utilisation de l'API ce mois-ci.

Une connexion fonctionnelle renvoie votre forfait et votre statut d'accès depuis whoami, les données des établissements depuis locations_all et les compteurs d'utilisation depuis get_usage. Une clé incorrecte ou expirée entraîne une erreur Unauthenticated au premier appel d'outil, et non lors de la découverte.

Premières instructions pour l'agent à essayer une fois la connexion établie :

• "Listez mes établissements dont les fiches présentent des erreurs et résumez chaque erreur."
• "Affichez les avis reçus au cours des 7 derniers jours qui n'ont pas de réponse et rédigez une réponse pour chacun. Ne les envoyez pas encore."
• "Comparez les statistiques de la fiche Google de l'établissement 1800289 sur les deux derniers mois."
• "Lisez le contrat du point de terminaison create-location, puis ajoutez cet établissement : ..."

Ajoutez les compétences d’agent listingsAPI

Les compétences sont des instructions qu’un agent charge lorsqu’une tâche correspond, afin de suivre une procédure éprouvée plutôt que d’en élaborer une. Elles fonctionnent avec le serveur MCP : le serveur effectue les appels, et la compétence détermine les appels à effectuer et leur ordre. Cinq compétences listingsAPI sont publiées sur skills.sh à partir du dépôt public listingsapi-mcp :

Installez les cinq compétences dans votre projet avec la CLI Skills :

npx skills add listings-api/listingsapi-mcp

Vous pouvez aussi en installer une par son nom et choisir l’agent avec -a :

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

Utilisez -a cursor ou -a codex pour ces agents, et ajoutez -g pour installer les compétences pour tous les projets plutôt que pour le projet actuel.

Trouvez listingsAPI dans les annuaires d’outils d’IA

Le même serveur est répertorié dans ces annuaires, aux côtés de la compétence d’agent listingsAPI. Effectuez l’installation depuis l’annuaire que votre client utilise déjà. Chaque entrée de serveur MCP pointe vers https://listingsapi.com/mcp.

Dépannage

Étapes suivantes

• Choisir une méthode d’intégration : quand MCP convient et quand REST ou un SDK constitue un meilleur choix.
• Effectuer votre premier appel API : obtenez une clé et découvrez la structure des réponses renvoyées par les outils.
• Réagir aux événements avec des webhooks : faites en sorte que la plateforme avertisse votre agent plutôt que de l’interroger périodiquement.
• Consultez Authentification et Codes d’erreur pour les codes que l’assistant vous transmettra.