> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sécurité, pagination et erreurs MCP

> Créez des clients MCP Chataigne fiables avec résultats bornés, écritures optimistes, idempotence et erreurs sûres.

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 :

```json theme={null}
{
  "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 :

```json theme={null}
{
  "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 :

```json theme={null}
{
  "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.