Protocole MCP et découverte

Transport, contexte, schémas, résultats et limites.

Vérifié le 2026-10-12 · Version Markdown

Transport#

Le serveur est exposé en POST /api/mcp, en Streamable HTTP sans session serveur persistante. Chaque requête est authentifiée. Les réponses sont JSON ; GET et DELETE répondent 405 et il n'y a pas de flux SSE durable.

Un client MCP doit négocier la connexion selon le protocole qu'il prend en charge. Utilisez de préférence un SDK compatible et les métadonnées de découverte du serveur. Ne supposez pas qu'un test HTTP sans authentification décrit les capacités réelles.

OAuth et découverte#

Le 401 du MCP fournit un challenge avec la ressource protégée. L'organisation sert /.well-known/oauth-protected-resource/api/mcp et les métadonnées du serveur d'autorisation. Le flux personnel utilise un client public, un code d'autorisation avec PKCE S256 et le rafraîchissement autorisé.

La ressource doit correspondre à l'hôte de l'organisation. Ne choisissez pas une URL de retour arbitraire et ne désactivez pas la vérification d'état ou de PKCE pour débloquer une connexion.

Ordre de travail d'un assistant#

1. Lisez /llms.txt sur l'instance pour l'orientation générale.
2. Appelez load_context pour le vocabulaire, le porteur du jeton, les capacités, les quotas et le travail ouvert.
3. Appelez describe_schema avant d'inventer une structure ou d'écrire un champ.
4. Consultez tools/list pour les outils et leurs schémas effectivement autorisés.
5. Recherchez les objets existants, puis appelez l'outil métier adapté.
6. Vérifiez le résultat, y compris les validations et demandes d'approbation.

Les ressources cercla://context et cercla://schema donnent les équivalents des deux outils de découverte. load_context accepte ifNoneMatch pour éviter de retransmettre un contexte inchangé.

Périmètre et schémas#

La référence de ce site recense les définitions du dépôt. Le serveur filtre le catalogue selon l'identité et les scopes. Des gardes complémentaires s'appliquent à l'exécution, notamment pour les outils composés et les documents rattachés.

Les schémas de tools/list sont ceux de la version installée. describe_schema ajoute les noms personnalisés et les champs de l'organisation. Ne réutilisez pas le schéma d'une autre organisation sans vérification.

Résultats et erreurs#

Les erreurs de transport sont JSON-RPC avec les statuts HTTP appropriés. Un outil peut aussi retourner une erreur métier dans son résultat. Vérifiez le contenu et l'indicateur d'erreur du SDK ; un HTTP 200 ne prouve pas qu'une action a abouti.

La section capabilities de load_context dit, par domaine, ce que le jeton peut lire ou modifier, les outils qui lui sont fermés et ceux qui passent par une approbation. Un refus porte sa cause et son remède : scope_not_granted (accès non coché au consentement, ou non accordé à l'application connectée), profile (le profil d'accès de la personne ne le permet pas, un administrateur doit agir), module_off (application arrêtée pour l'organisation), record_read_only (fiche partagée en lecture seule). Une fiche hors du périmètre reste introuvable. Des arguments invalides sont signalés champ par champ.

La pagination MCP utilise couramment 20 éléments par défaut et un plafond de 200. Les outils particuliers peuvent avoir leur propre limite. Respectez les curseurs et les refus de quota.

Idempotence#

Les outils d'écriture reçoivent idempotency_key. Conservez une clé par intention logique et réutilisez-la après une coupure ou pour retrouver le résultat d'une demande déjà soumise. Changer de clé à chaque reprise peut produire une seconde action.

Une réponse pending_approval impose d'attendre et de suivre l'approbation ; elle n'autorise pas à passer par un autre outil pour contourner le contrôle.

Matrice de couverture#

Générée depuis le catalogue des outils et le contrat OpenAPI v1 : chaque case objet:verbe a un outil, ou une décision (exclusion d'ADR-205 D1, ou travail à faire suivi par une issue).

119 cases : 87 couvertes par un outil, 22 à faire, 10 exclues (liste fermée d'ADR-205 D1).