Serveur MCP — connecter une IA à vos annonces

En plus de l'API REST, NGZ Ads expose un serveur MCP (Model Context Protocol) : le standard ouvert qui permet à un assistant IA comme Claude ou ChatGPT d'utiliser directement des outils externes, sans intégration sur mesure.

Concrètement, cela permet à un utilisateur de demander en langage naturel — « trouve-moi des annonces de vélo à moins de 200 € » — et à l'assistant d'aller chercher la vraie réponse dans les données de NGZ Ads, en temps réel.

Ce que le serveur MCP expose

Le serveur (mcp-server/http.php) partage exactement la même logique et les mêmes identifiants que l'API REST. Il expose six outils :

Outil	Ce qu'il fait	Argument requis
`ngzads_status`	Vérifie que l'API répond	—
`ngzads_search_ads`	Recherche des annonces (mot-clé, catégorie, prix, ville, tri...)	—
`ngzads_get_ad`	Détail complet d'une annonce	`id`
`ngzads_list_categories`	Arborescence des catégories	—
`ngzads_list_pages`	Liste des pages statiques publiées	—
`ngzads_get_page`	Contenu d'une page statique	`slug`

Deux façons de s'y connecter

En local (stdio)

mcp-server/ngzads-mcp-server.php tourne comme un simple processus PHP, spawné localement par un client MCP (par exemple un IDE ou un outil de développement). Il lit ses identifiants dans des variables d'environnement :

NGZADS_API_BASE=https://votre-site.com/api/v1 \
NGZADS_APP_ID=app_xxx \
NGZADS_APP_SECRET=sk_xxx \
php mcp-server/ngzads-mcp-server.php

À distance (HTTP — pour Claude, ChatGPT...)

mcp-server/http.php expose le même ensemble d'outils sur une URL HTTPS unique — c'est ce qu'il faut renseigner comme connecteur dans un assistant IA hébergé :

https://votre-site.com/mcp-server/http.php

Aucune variable d'environnement ici : les identifiants voyagent avec chaque requête, exactement comme pour l'API REST (en-têtes X-App-Id / X-App-Secret, ou Authorization: Bearer app_id.secret).

Le serveur doit être joignable en HTTPS depuis l'Internet public pour ce mode — un assistant IA hébergé (Claude, ChatGPT) ne peut pas atteindre un localhost.

Obtenir vos identifiants

Les identifiants sont les mêmes que pour l'API REST — pas besoin d'en créer de nouveaux si vous en avez déjà :

Admin → API Apps → créez une application dédiée (par exemple « Claude » ou « ChatGPT », pour suivre son usage séparément dans les logs).
Copiez immédiatement l'App ID et l'App Secret affichés — le secret ne sera plus jamais visible en clair.

Connecter Claude

Dans Claude, ouvrez Customize → Connectors (Pro/Max), ou Organization settings → Connectors si vous êtes propriétaire d'un espace Team/Enterprise.
Cliquez Add custom connector (connecteur personnalisé).
Renseignez l'URL du serveur : https://votre-site.com/mcp-server/http.php.
Dans les options avancées, ajoutez un en-tête de requête :

Authorization: Bearer app_xxx.sk_xxx

Enregistrez. Claude découvre automatiquement les six outils ci-dessus.
Testez en demandant par exemple : « Utilise NGZ Ads pour chercher des annonces de vélo à moins de 200 €. »

Connecter ChatGPT

Dans ChatGPT, ouvrez Réglages → Connecteurs (Connectors).
Cliquez Avancé (Advanced), puis activez le Mode développeur (Developer mode).
Un bouton Ajouter un connecteur personnalisé apparaît dans le panneau des connecteurs — cliquez dessus (un avertissement de sécurité sur l'exécution de code tiers s'affiche, à accepter en connaissance de cause).
Renseignez l'URL du serveur : https://votre-site.com/mcp-server/http.php.
Pour l'authentification, ChatGPT propose OAuth ou coller un jeton : utilisez cette seconde option avec app_xxx.sk_xxx.
Cliquez Créer, puis Scanner les outils (Scan Tools) pour vérifier que la connexion fonctionne.
Testez avec une question similaire à celle utilisée pour Claude.

ChatGPT ne se connecte qu'à des serveurs MCP distants (HTTPS) — un serveur local nécessiterait un tunnel (type mcp-remote) pour être joignable.

Les intitulés exacts des menus évoluent régulièrement côté Claude et ChatGPT ; le principe reste le même : une URL de serveur MCP + un moyen d'authentification (ici, un jeton Bearer).

Exemple de conversation

Utilisateur : Trouve-moi des annonces d'appareils photo à moins de 150 € sur NGZ Ads. Assistant : (appelle l'outil ngzads_search_ads avec {"q": "appareil photo", "max_price": 150}) J'ai trouvé 3 annonces : ...

L'assistant interroge directement vos vraies données — pas d'approximation, pas d'invention.

Sécurité

Le jeton (app_id.secret) transite uniquement en HTTPS et ne doit être collé que dans l'interface officielle de l'assistant IA — jamais partagé ailleurs.
Si un jeton est compromis, régénérez l'App Secret depuis Admin → API Apps — l'ancien secret est immédiatement invalidé.
Chaque appel MCP est journalisé comme n'importe quel appel API, consultable dans Admin → API Logs.

Vérifier manuellement (curl)

Pour tester le serveur MCP sans passer par un assistant IA :

curl -X POST "https://votre-site.com/mcp-server/http.php" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer app_xxx.sk_xxx" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Une collection Postman complète (API REST + serveur MCP) est également disponible auprès de l'administrateur du site pour des tests approfondis.