Skip to content

Reliability

The Contio User API and hosted MCP gateway are built for production agent workloads. This page describes the reliability behaviors you can expect and how to build resilient clients.

Status and health

  • Status page: status.contio.ai
  • Gateway health: GET https://mcp.contio.ai/health
  • Gateway version: GET https://mcp.contio.ai/version

Availability

We target 99.9% monthly uptime for the User/Workspace API and hosted MCP gateway. Scheduled maintenance is posted on the status page at least 24 hours in advance. Emergency maintenance is posted as soon as possible.

Retries

  • Retry 5xx and network errors with exponential backoff. We recommend 3 attempts starting at 500 ms.
  • Do not retry 4xx errors without fixing the request.
  • Idempotent operations (marked in operations.json with idempotent: true) are safe to retry.
  • Non-idempotent writes should not be blindly retried.

Tracing

  • Every request is assigned an X-Request-ID.
  • The gateway propagates X-Request-ID to the Contio API, so a tool call can be traced end-to-end.
  • Include X-Request-ID and the UTC timestamp when reporting issues.

Rate limits

See Rate limits.

Hosted MCP client best practices

  • Preserve session affinity for live events. The hosted MCP gateway uses stateful sessions behind an Application Load Balancer with cookie-based stickiness. Your HTTP client must accept and forward the ALB's sticky-session cookie on every request if you want SSE contio-events. Not all MCP SDK clients do this by default — some only send the mcp-session-id header.
  • Use webhooks for cookie-less integrations. If your MCP SDK client does not preserve cookies, tool calls still work statelessly, but the SSE contio-events resource returns 405 Method Not Allowed on GET and an error on resources/subscribe. Configure a workspace webhook to receive the same events without cookies.
  • Handle session loss. If a cookie-aware client receives 404 Session not found, its session was lost (for example, during a deployment or task replacement). Re-initialize and re-subscribe to contio-events.
  • Reconnect events. contio-events reconnects with Last-Event-ID when the SSE stream resumes. Subscriptions are per session; you must re-subscribe after reconnecting.
  • Event stream resilience. Workspace events are buffered in a Redis-backed SSE stream. Brief disconnects between the hosted gateway and the Contio API resume automatically using Last-Event-ID replay; events that fall outside the retention window cannot be recovered.
  • Idempotent mutations. Mutating MCP tools accept an optional Idempotency-Key argument. If you omit it, the gateway automatically generates one for operations that support it and reuses the same key across internal 5xx retries. If you supply your own key, the gateway forwards it unchanged; reuse the same key when retrying from your client.
  • Graceful close. Keep-alive connections are closed gracefully during deploys. A well-behaved MCP client should reconnect automatically.

Getting help

  • Check status.contio.ai for known incidents.
  • Contact support with the endpoint, X-Request-ID, and UTC timestamp.