Connecter un agent IA avec MCP

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

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 endpoint REST ainsi que quelques outils de documentation, puis les appelle sur votre compte. Ce guide vous explique comment connecter chacun des principaux clients, puis vérifier la connexion.

1. Comprendre les outils accessibles à l’agent

Le serveur expose un peu plus de 60 outils, dont environ les deux tiers sont en lecture seule. Leurs noms suivent ceux des ressources REST : locations_search, listings_premium, reviews_respond et posts_create_social effectuent donc les mêmes opérations que les endpoints 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 endpoint au lieu de deviner la structure des données à envoyer.

Les opérations destructrices, 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 de données de sa propre initiative.

2. Choisir le mode de connexion du client

Chaque client s’authentifie de l’une des deux façons suivantes. Toutes deux aboutissent à la même 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 délivrés à 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 ne demande aucune portée 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 sont 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 +, puis 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 offres Team et Enterprise, un propriétaire ajoute le connecteur dans Organization settings (Paramètres de l’organisation), puis 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 de 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"

Supprimez l’option --header et exécutez /mcp dans Claude Code pour vous connecter via le navigateur à la place. Utilisez --scope project pour enregistrer la configuration du serveur dans un fichier .mcp.json partagé par toute l’équipe et l’inclure dans un commit ; n’y incluez pas de clé.

4. Connecter ChatGPT

ChatGPT se connecte aux serveurs MCP distants au moyen d’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 nécessitent toujours une confirmation.

Codex CLI. L’agent de terminal 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 accessible à l’adresse /dashboard/mcp comporte un bouton Add to Cursor (ajouter à Cursor). Ce bouton ouvre un lien d’installation pour Cursor avec l’URL du serveur et votre clé déjà renseignées, ce qui permet de terminer la configuration en un clic.

Pour une configuration manuelle, ajoutez le serveur à ~/.cursor/mcp.json pour tous les projets, ou à .cursor/mcp.json dans 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 (se connecter) sur l’entrée du serveur sous Settings (paramètres), puis MCP, et ouvre le parcours de connexion dans le navigateur. N’incluez jamais de clé dans un fichier .cursor/mcp.json au niveau du projet lors d’un commit ; utilisez le fichier global ou OAuth pour les dépôts partagés.

6. Connecter Gemini

Gemini CLI. L’agent de terminal de Google accepte 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 }, lancez la CLI 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 informations 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 PKCE publics 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 plutôt avec la Gemini API.

Développer avec la Gemini API. Le SDK de la Gemini API accepte une session client MCP comme outil, ce qui permet à un script de 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 faire confiance à 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, formulez une demande qui nécessite d’accéder à votre compte :

Utilisez les outils listingsapi pour m’indiquer à quel compte je suis connecté, combien d’établissements il contient et quelle est mon utilisation de l’API ce mois-ci.

Une connexion correcte fournit une réponse issue de whoami, locations_all et get_usage avec l’identifiant réel de votre compte et les décomptes réels. Une clé incorrecte ou expirée entraîne une erreur Unauthenticated lors du premier appel d’outil, et non lors de la découverte.

Quelques premières instructions pour l’agent utiles une fois la connexion opérationnelle :

• "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 données d’analyse de la fiche Google de l’établissement 1800289 sur les deux derniers mois."
• "Lisez le contrat de l’endpoint create-location, puis ajoutez cet établissement : ..."

Ajouter les compétences listingsAPI pour les agents

Les compétences sont des instructions qu’un agent charge lorsqu’une tâche correspond, afin de suivre un processus éprouvé plutôt que d’en élaborer un. Elles fonctionnent avec le serveur MCP : le serveur effectue les appels, et la compétence détermine lesquels effectuer et dans quel 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

Ou installez une compétence en indiquant son nom, puis choisissez 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 la compétence pour tous les projets plutôt que pour le projet actuel.

Trouver listingsAPI dans les annuaires d’outils d’IA

Le même serveur figure dans ces annuaires, aux côtés de la compétence listingsAPI pour les agents. 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 votre mode 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.
• Authentification et Codes d’erreur pour les codes que l’assistant vous communiquera.