MCP : brancher votre assistant

Le protocole, pour vos développeurs

Model Context Protocol : la prise standard par laquelle un assistant IA utilise un outil à la place de l’agence. Un seul point, POST https://geo.greeneris.io/agence/mcp/, du JSON-RPC 2.0, un message par requête, une réponse JSON. Pas de flux serveur : le GET répond 405. Écrit à la main, sans bibliothèque. Chaque outil appelle la même fonction que la route de l’API : mêmes règles, mêmes refus, mêmes mots.

• Versions du protocole : 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, dans l’en-tête MCP-Protocol-Version. Absent, 2025-03-26. Inconnue, 400.
• Authentification : la clé du compte dans x-api-key, ou un jeton OAuth dans Authorization: Bearer. Sans l’un ni l’autre, 401 avec un défi WWW-Authenticate, pour initialize aussi : c’est ce 401 qui fait proposer « Connecter » à Claude.ai.
• Méthodes : initialize, ping, tools/list, tools/call, et les notifications (sans id, accusées par un 202 vide). Ni resources ni prompts.
• Origine : un en-tête Origin est refusé (403). Cette porte est faite pour un serveur, pas pour une page ouverte dans un navigateur.
• Erreurs de protocole : -32700 JSON illisible, -32600 requête invalide, -32601 méthode inconnue, -32603 l’outil n’a pas abouti, -32001 refusé (clé, compte suspendu, trop d’appels). Un refus métier (plus de place, déjà retiré) est un résultat avec isError: true : l’assistant doit pouvoir le lire et l’expliquer.
• Résultats : le même objet que la route correspondante, en texte dans content et en structuredContent. Chaque outil porte ses annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) et ses instructions disent à l’assistant pour qui il travaille : une agence cliente.
• Limites : 600 appels par heure et par clé ou par connexion. Le compte est relu en base à chaque appel : un compte en pause ne commande plus.

# Le compte, par le MCP : la même fonction que GET /agence/v1/compte/
curl -X POST https://geo.greeneris.io/agence/mcp/ \
  -H "x-api-key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "compte", "arguments": {}}}'

# La liste des vingt outils, avec leur schéma d'entrée et leurs annotations
curl -X POST https://geo.greeneris.io/agence/mcp/ \
  -H "x-api-key: VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{ ...le même JSON, indenté... }"}],
    "structuredContent": { "slug": "...", "nom": "...", "plafond": 5, "places_restantes": 2 },
    "isError": false
  }
}

OAuth 2.1

C’est ainsi que Claude.ai, Claude Desktop et ChatGPT se connectent, sans clé. Clients publics enregistrés dynamiquement, PKCE S256 obligatoire, indicateur de ressource, rotation des jetons de rafraîchissement, iss dans chaque retour. L’agence s’identifie sans mot de passe : par un lien reçu à l’adresse email de son compte, cliqué dans le même navigateur. Un jeton OAuth n’ouvre que le MCP, jamais /agence/v1/ : un programme prend la clé.

1. L’assistant appelle le MCP sans jeton et reçoit 401. Le défi pointe les métadonnées de la ressource (RFC 9728).
2. GET /.well-known/oauth-protected-resource : resource, authorization_servers (le service lui-même), scopes_supported (agence).
3. GET /.well-known/oauth-authorization-server (RFC 8414) : les trois points ci-dessous, S256, none comme seule méthode d’authentification du client.
4. POST /agence/oauth/enregistrer/ (RFC 7591) : {"redirect_uris": [...]}, en https ou http://localhost, et un client_name facultatif. 201 avec client_id. Vingt par heure et cent par jour par adresse IP.
5. GET /agence/oauth/autoriser/ avec response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 et resource=https://geo.greeneris.io/agence/mcp/. Le service vérifie et envoie l’agence sur la fenêtre de connexion du site ; elle y écrit l’adresse email de son compte, clique le lien reçu, et la fenêtre repart vers redirect_uri avec code, state et iss. Un client ou un retour inconnus renvoient vers la page du site, jamais vers une adresse inconnue.
6. POST /agence/oauth/jeton/, en application/x-www-form-urlencoded : le code contre un jeton d’accès d’une heure et un jeton de rafraîchissement de trente jours. Puis grant_type=refresh_token, avec rotation : un code ou un jeton déjà servi qui revient coupe toute la connexion. Erreurs aux codes de la RFC 6749 (invalid_grant, invalid_target…).
7. Le MCP s’appelle avec Authorization: Bearer. Un jeton échu ou coupé rend 401 invalid_token : l’assistant rafraîchit, ou refait la connexion. « Révoque ma clé » coupe aussi tous les assistants connectés.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://geo.greeneris.io/.well-known/oauth-protected-resource", scope="agence"
{"error": "invalid_token", "error_description": "connexion requise"}

curl -X POST https://geo.greeneris.io/agence/oauth/jeton/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=LE_CODE&client_id=LE_CLIENT_ID" \
  -d "redirect_uri=https://exemple.fr/retour&code_verifier=LE_VERIFIER" \
  -d "resource=https://geo.greeneris.io/agence/mcp/"

# {"access_token": "...", "token_type": "Bearer", "expires_in": 3600,
#  "refresh_token": "...", "scope": "agence"}