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.

Famille d’outilsExemplesDroits requis
Établissementslocations_all, locations_search, locations_create, locations_updateRead pour la consultation, Write pour la création et la mise à jour
Ficheslistings_premium, listings_duplicates, listings_mark_duplicateRead, Write pour le marquage des doublons
Comptes connectésconnected_accounts_list, connected_accounts_listings, connected_accounts_connect_listingRead, Write pour la connexion et l’importation
Avisreviews_list, reviews_get, reviews_respond, reviews_analyticsRead, Write pour les réponses
Publicationsposts_social_post_view, posts_create_socialRead, Write pour publier
Statistiquesanalytics_google, analytics_facebook, analytics_bing (obsolète, ne renvoie aucune donnée)Read
Comptewhoami, get_usage, get_subscription, recent_errorsRead
Documentationsearch_docs, get_doc, get_endpoint, list_endpointsAucun

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.

MéthodeCe que vous collezUsage recommandé
En-tête de clé APIAuthorization: API <your key> comme en-tête statiqueInterfaces en ligne de commande et éditeurs dont vous contrôlez le fichier de configuration
OAuth 2.0Rien. Le client ouvre un navigateur, vous vous connectez et approuvez read ou read writeAssistants hébergés tels que Claude et ChatGPT, ou toute personne qui ne devrait pas détenir une clé en clair

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 Code
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.

  1. 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).
  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. 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 :

~/.codex/config.toml
[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é :

~/.cursor/mcp.json
{"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 :

~/.gemini/settings.json
{"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 :

Register an OAuth client
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 :

gemini_agent.py
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 :

List the tools
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, 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 :

CompétenceFonction
listingsapi-integrationAjoute la Listings API à votre application : authentification, première lecture, établissements, connexions aux plateformes de publication et état de synchronisation, via REST ou un SDK.
listingsapi-listing-auditVérifie l’état de synchronisation, les liens actifs et les doublons potentiels des établissements et de leurs fiches, puis propose des corrections. Fonctionne en lecture seule jusqu’à ce que vous approuviez une correction.
listingsapi-review-managementConstitue une file d’avis à traiter, donne la priorité aux avis sans réponse, prépare des réponses et publie uniquement celles que vous approuvez.
listingsapi-multi-location-postingPrépare et publie des annonces, des événements et des offres sur Google Business Profile et Facebook pour les établissements que vous choisissez, puis vérifie chaque résultat.
listingsapi-performance-reportingGénère des rapports en lecture seule sur les performances et les avis de vos établissements.

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

All skills
npx skills add listings-api/listingsapi-mcp

Ou installez une compétence en indiquant son nom, et choisissez l’agent avec -a :

One skill, for Claude Code
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.

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.

AnnuaireÉlément répertorié
Annuaire des connecteurs ClaudeLe serveur MCP en tant que connecteur Claude. Cliquez sur Connect (se connecter) et connectez-vous.
Registre officiel MCPLe serveur MCP, enregistré sous le nom com.listingsapi/mcp.
Annuaire CursorLe serveur MCP en tant que plugin Cursor.
GlamaLe serveur MCP.
SmitheryLe serveur MCP.
MCP.soLe serveur MCP.
mcpservers.orgLe serveur MCP.
ClawHub (OpenClaw)La compétence listingsAPI pour les agents.
skills.shLa compétence listingsAPI pour les agents.

Dépannage

SymptômeCauseSolution
401 lors du premier appel d’outilLa clé a été mal saisie ou révoquée, ou l’en-tête ne contient pas le mot exact API suivi d’une espaceRecréez la clé dans /dashboard/keys et collez-la sous la forme API <key>
SY90016 lors d’une écritureClé de lecture ou portée readReconnectez-vous avec une clé d’écriture ou approuvez write
429 avec Retry-AfterL’agent effectue des appels à une fréquence supérieure à celle autorisée par votre forfaitDemandez-lui de traiter des lots plus petits ; consultez Limites de débit
Le client indique qu’il ne peut pas joindre le serveurLe client prend uniquement en charge stdio ou SSEUtilisez un client compatible avec Streamable HTTP, ou la passerelle mcp-remote présentée sur /dashboard/mcp
Un outil mentionné dans la documentation est absentLes outils destructifs ne sont pas exposésUtilisez REST ou un SDK pour l’archivage et la suppression

Étapes suivantes