Skip to content

MCP vs. REST

The Contio User API is available through both a first-party REST API (/v1) and a hosted MCP gateway (mcp.contio.ai). They share the same backend, permissions, and data model, but they fit different integration styles.

When to use the MCP gateway

Choose MCP when you are building an agent, LLM-powered workflow, or coding-assistant integration.

  • Zero client code — the agent discovers tools, parameters, and descriptions at runtime.
  • Natural-language commands — "list my upcoming meetings" maps to the right tool call.
  • Typed inputs and outputs — every tool has a JSON schema; the agent validates before calling.
  • Live events — stateful sessions subscribe to contio-events for real-time workspace changes.
  • Session-oriented — the gateway maintains MCP session state and an SSE event stream.

Best for: Claude, Cursor, Windsurf, VS Code + Copilot, Cline, custom agents.

When to use the REST API

Choose /v1 REST when you are building traditional software, scripts, or need full control.

  • Full HTTP control — you manage retries, caching, and error handling.
  • Batch and automation — cron jobs, ETL, reporting, and back-office scripts.
  • No session state — each request is independent and stateless.
  • Available on every plan — the REST API is available on FREE and above.
  • Direct access to all endpoints — every /v1 operation has a documented REST equivalent.

Best for: servers, mobile apps, ETL, dashboards, integrations that do not need an LLM interface.

Feature comparison

REST API Hosted MCP
Transport HTTPS + JSON MCP 2024-11-05 streamable-http
Auth OAuth, PAT, or SLT OAuth, PAT, or SLT (forwarded to API)
Plan All plans PRO, ELITE, ENT
Self-hosted option Call API directly Build a private MCP server from mcp.json and authenticate with OAuth, PAT, or SLT
Discovery OpenAPI spec tools/list, mcp.json, operations.json
Events Webhooks + SSE /v1/user/events SSE contio-events resource
Retries Your responsibility Automatic 5xx/network retries with backoff; auto-generated Idempotency-Key for supported mutations
Schema validation Client-side Gateway validates before upstream call

PATs require PRO; SLTs are available on all plans

Creating a PAT requires a PRO or higher workspace. Short-lived access tokens are available on all plans and can be used for ad hoc MCP sessions where the hosted gateway is available. FREE users can still authenticate with OAuth and call the /v1 REST API directly.

Can I use both?

Yes. Many integrations use REST for background jobs and MCP for agent-facing features. They share the same workspace, scopes, and rate-limit budgets.

Next steps