MCP safety, pagination, and errors

Chataigne treats model calls as untrusted boundary input. The server validates schemas, rate and size boundaries, real resource ownership, OAuth scopes, live roles and memberships before calling business logic.

Response envelope

Successful tools return a short human-readable text block and structured data:

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

Keep request_id when reporting a problem. MCP arguments, customer message text, transcript queries and idempotency keys are not written to application logs or Sentry.

Pagination and limits

List tools default to 20 records and accept at most 50.
Cursors are opaque. Do not parse, edit or reuse them with different filters.
Conversation detail accepts at most 100 messages.
Analytics accepts at most eight metrics and a 366-day date range.
Structured output is limited to 128 KiB; text summaries to 4 KiB.
Each read tool allows 1,000 calls per minute per OAuth client/user; each write tool allows 500.
Standard reads time out after 15 seconds, analytics after 30 seconds, and merchant mutations after 20 seconds.

If meta.next_cursor is present, pass it unchanged to the same tool with the same filters.

Optimistic write preconditions

State-changing tools require the state the model previously observed. For example:

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

If another operator changes the order first, the server returns MCP_EXPECTED_STATE_MISMATCH or ORDER_STATUS_PRECONDITION_FAILED. Reload the resource, reconsider the requested change, and only then retry.

Idempotency

External message, instruction, organization-creation, and location-creation tools require an idempotency_key between 8 and 255 characters. The key is scoped to OAuth client, delegated user and tool.

The same key and same arguments replay the stored result for 24 hours.
The same key with different arguments returns MCP_IDEMPOTENCY_MISMATCH.
A concurrent duplicate returns MCP_OPERATION_IN_PROGRESS with a retry hint.
Raw keys are hashed before Redis storage and never logged.

Use one new high-entropy application-generated key per intended effect. Reuse it only when retrying that exact effect.

Error contract

Tool failures set isError: true and return:

{
  "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_..."
  }
}

Categories are validation, authentication, authorization, not_found, conflict, rate_limit, timeout, dependency, and internal.

Code	Meaning	Client action
`MCP_SCOPE_REQUIRED`	Required OAuth scope was not granted	Reconnect and explicitly consent to the scope
`MCP_RESOURCE_FORBIDDEN`	Scope, role or membership is insufficient	Do not retry unchanged
`MCP_RESOURCE_NOT_FOUND`	Authorized resource was not found	Verify the identifier
`MCP_CURSOR_INVALID`	Cursor is malformed or used incorrectly	Restart pagination
`MCP_EXPECTED_STATE_MISMATCH`	Resource changed after it was read	Reload before deciding
`MCP_IDEMPOTENCY_MISMATCH`	Key was reused for a different effect	Use the original arguments or a new key
`MCP_OPERATION_IN_PROGRESS`	Identical effect is still running	Retry after the supplied delay
`MCP_TOOL_TIMEOUT`	A read deadline expired	Retry or narrow the query
`MCP_OUTCOME_UNKNOWN`	A write exceeded the client deadline	Read the resource state; never retry blindly
`MCP_OUTPUT_TOO_LARGE`	Request is too broad	Narrow filters or paginate
`MCP_INTERNAL_ERROR`	Unexpected safe failure	Retry once and report the request ID

Deliberately unavailable operations

The restaurant surface does not expose payment capture, refund, cancellation/rejection, destructive deletion, bulk export, campaigns, credentials, provider synchronization, full onboarding or platform administration. Do not attempt to emulate omitted setup operations by combining restaurant tools.

​Response envelope

​Pagination and limits

​Optimistic write preconditions

​Idempotency

​Error contract

​Deliberately unavailable operations