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 endpoint REST ainsi que quelques outils de documentation, et les appelle sur votre compte. Ce guide explique comment connecter chacun des principaux clients, puis vérifier la connexion.
1. Comprendre ce qui est accessible à l’agent
Le serveur expose un peu plus de 60 outils, dont environ deux tiers en lecture seule. Leurs noms reprennent 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, telles que 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 selon l’une des deux méthodes suivantes. Les deux méthodes utilisent en définitive le même type 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 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 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, puis 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 + 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 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"Omettez l’option --header et exécutez /mcp dans Claude Code pour vous connecter plutôt par le navigateur. 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 à l'aide 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.
- Ouvrez Settings (paramètres) depuis le menu de votre profil et activez Developer mode (mode développeur). Selon la version, ce réglage se trouve sous Apps & Connectors (applications et connecteurs) ou Security and login (sécurité et connexion).
- Sur la page des connecteurs (intitulée Plugins (extensions) dans les versions actuelles), cliquez sur + ou Create (créer).
- Saisissez un nom, collez
https://listingsapi.com/mcpcomme URL du serveur et choisissez OAuth pour l'authentification. Enregistrez. - ChatGPT ouvre la page de connexion. Approuvez
readouread write. - Dans une nouvelle conversation, ouvrez le menu des outils, sélectionnez le connecteur et vérifiez qu'il apparaît avec ses outils. L'utilisation des outils d'écriture reste soumise à 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). Ce bouton ouvre un lien d'installation dans Cursor avec l'URL du serveur et votre clé déjà renseignées ; un clic suffit donc pour terminer la configuration.
Pour le configurer manuellement, ajoutez le serveur à ~/.cursor/mcp.json pour l'ensemble des projets, ou à .cursor/mcp.json dans un dépôt donné :
{"mcpServers": { "listingsapi": { "url": "https://listingsapi.com/mcp", "headers": { "Authorization": "API <your key>" } }}}Supprimez le bloc headers pour vous connecter avec OAuth : Cursor affiche un bouton Connect (se connecter) dans l'entrée du serveur sous Settings (paramètres), puis MCP, et ouvre le parcours d'authentification dans le navigateur. N'enregistrez jamais de clé dans un fichier .cursor/mcp.json propre au 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 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 réglage pour les connecteurs personnalisés. 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 d'obtention du 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 une intégration avec l'API Gemini.
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 capable d'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 400Ensuite, dans l'assistant, demandez une opération qui nécessite d'accéder à 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 lors du premier appel d'outil, et non lors de la découverte.
Premières instructions pour l'agent à essayer une fois la connexion fonctionnelle :
- "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 listingsAPI pour les agents
Les compétences sont des instructions qu’un agent charge lorsqu’une tâche correspond, afin de suivre une procédure testée au lieu 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-mcpOu installez une compétence en indiquant son nom, et choisissez l’agent avec -a :
npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-codeUtilisez -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.
Trouvez 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 du serveur MCP pointe vers https://listingsapi.com/mcp.
Dépannage
Étapes suivantes
- Choisir une méthode d’intégration : quand utiliser MCP et quand privilégier REST ou un SDK.
- Effectuer votre premier appel d’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 au lieu d’effectuer des interrogations périodiques.
- Consultez Authentification et Codes d’erreur pour connaître les codes que l’assistant vous transmettra.