Sécurité, pagination et erreurs MCP

Chataigne traite les appels de modèles comme des entrées non fiables à la frontière du système. Avant la logique métier, le serveur valide les schémas, limites de taille et de fréquence, le véritable propriétaire de la ressource, les scopes OAuth, les rôles et les memberships actuels.

Enveloppe de réponse

Les outils renvoient un court texte lisible et des données structurées :

{
  "data": {
    "orders": []
  },
  "meta": {
    "request_id": "req_...",
    "next_cursor": "opaque-cursor",
    "truncated": false,
    "replayed": false
  }
}

Conservez request_id pour signaler un problème. Les arguments MCP, textes de messages client, recherches de transcription et clés d’idempotence ne sont jamais envoyés aux logs applicatifs ni à Sentry.

Pagination et limites

Les listes renvoient 20 éléments par défaut, 50 maximum.
Les curseurs sont opaques. Ne les analysez pas, ne les modifiez pas et ne les réutilisez pas avec d’autres filtres.
Le détail d’une conversation accepte 100 messages maximum.
Les analytics acceptent huit métriques et 366 jours maximum.
La sortie structurée est limitée à 128 Kio, le résumé texte à 4 Kio.
Chaque outil de lecture accepte 1 000 appels par minute et par couple client/utilisateur OAuth ; chaque outil d’écriture en accepte 500.
Les lectures standard expirent après 15 secondes, les analytics après 30 secondes et les mutations restaurant après 20 secondes.

Si meta.next_cursor est présent, transmettez-le inchangé au même outil avec les mêmes filtres.

Préconditions d’écriture optimiste

Les outils qui modifient un état exigent la valeur précédemment observée. Exemple :

{
  "order_id": "ord_...",
  "status": "accepted",
  "expected_status": "received"
}

Si un autre opérateur modifie la commande avant l’appel, le serveur renvoie MCP_EXPECTED_STATE_MISMATCH ou ORDER_STATUS_PRECONDITION_FAILED. Rechargez la ressource, réévaluez le changement, puis seulement ensuite réessayez.

Idempotence

Les outils externes de message, d’instruction, de création d’organisation et de création de restaurant exigent une idempotency_key de 8 à 255 caractères. La clé est scoped par client OAuth, utilisateur délégué et outil.

La même clé avec les mêmes arguments rejoue le résultat conservé pendant 24 heures.
La même clé avec d’autres arguments renvoie MCP_IDEMPOTENCY_MISMATCH.
Un doublon concurrent renvoie MCP_OPERATION_IN_PROGRESS avec un délai conseillé.
Les clés brutes sont hashées avant stockage Redis et ne sont jamais loggées.

Utilisez une nouvelle clé à forte entropie générée par l’application pour chaque effet voulu. Réutilisez-la uniquement pour réessayer exactement cet effet.

Contrat d’erreur

Les erreurs d’outil définissent isError: true et renvoient :

{
  "data": {
    "error": {
      "code": "MCP_RESOURCE_FORBIDDEN",
      "category": "authorization",
      "retryable": false,
      "message": "The resource is unavailable or your delegated access is insufficient.",
      "request_id": "req_..."
    }
  },
  "meta": {
    "request_id": "req_..."
  }
}

Les catégories sont validation, authentication, authorization, not_found, conflict, rate_limit, timeout, dependency et internal.

Code	Signification	Action client
`MCP_SCOPE_REQUIRED`	Scope OAuth non accordé	Reconnecter et consentir explicitement
`MCP_RESOURCE_FORBIDDEN`	Scope, rôle ou membership insuffisant	Ne pas réessayer à l’identique
`MCP_RESOURCE_NOT_FOUND`	Ressource autorisée introuvable	Vérifier l’identifiant
`MCP_CURSOR_INVALID`	Curseur invalide ou mal réutilisé	Recommencer la pagination
`MCP_EXPECTED_STATE_MISMATCH`	Ressource modifiée depuis la lecture	Recharger avant décision
`MCP_IDEMPOTENCY_MISMATCH`	Clé réutilisée pour un autre effet	Reprendre les arguments initiaux ou une nouvelle clé
`MCP_OPERATION_IN_PROGRESS`	Effet identique encore en cours	Réessayer après le délai fourni
`MCP_TOOL_TIMEOUT`	Délai d’une lecture dépassé	Réessayer ou réduire la requête
`MCP_OUTCOME_UNKNOWN`	Une écriture a dépassé le délai client	Lire l’état ; ne jamais réessayer aveuglément
`MCP_OUTPUT_TOO_LARGE`	Requête trop large	Réduire les filtres ou paginer
`MCP_INTERNAL_ERROR`	Échec inattendu sécurisé	Réessayer une fois et transmettre le request ID

Opérations volontairement absentes

La surface restaurant n’expose ni capture de paiement, remboursement, annulation/rejet, suppression destructive, export massif, campagne, credential, synchronisation provider, onboarding complet ou administration de plateforme. N’essayez pas de reproduire les étapes de configuration absentes en combinant les outils restaurant.

​Enveloppe de réponse

​Pagination et limites

​Préconditions d’écriture optimiste

​Idempotence

​Contrat d’erreur

​Opérations volontairement absentes