Hosted MCP Server¶

The Contio User API is also available as a hosted Model Context Protocol (MCP) server. Instead of writing REST calls, an MCP-compatible agent can discover Contio tools, invoke them with typed parameters, and subscribe to live workspace events.

Why MCP¶

MCP turns Contio into a first-class agent integration:

• Zero client code — the server exposes every tool, its JSON schema, and descriptions; the agent decides what to call.
• Natural language to action — requests like "list my upcoming meetings" or "create an action item to follow up with the client" map directly to tool calls.
• Live workspace events — cookie-aware clients can subscribe to the contio-events SSE resource; cookie-less clients can receive the same events through the GET /v1/user/events SSE endpoint or workspace webhooks.
• Same security model — the gateway forwards your bearer token to the Contio API, so workspace roles, scopes, and plan limits are always respected.

Hosted vs. self-hosted¶

Contio runs a public MCP gateway for paid workspaces. Free workspaces keep full API access and can build or self-host their own MCP server.

Endpoint¶

The hosted gateway speaks MCP 2024-11-05 streamable-http:

https://mcp.contio.ai/mcp

OAuth discovery is published at:

GET https://mcp.contio.ai/.well-known/oauth-protected-resource
GET https://mcp.contio.ai/.well-known/oauth-authorization-server
GET https://mcp.contio.ai/.well-known/openid-configuration

Connect your MCP client¶

Authorization: Bearer cto_at_v1_...

URL:    https://mcp.contio.ai/mcp
Transport: http (streamable-http)
Auth:   Bearer cto_slt_v1_<your-token>

URL:    https://mcp.contio.ai/mcp
Transport: http (streamable-http)
Auth:   Bearer cto_pat_v1_<your-token>

curl -X POST https://mcp.contio.ai/mcp \
  -H "Authorization: Bearer cto_pat_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example", "version": "1.0.0"}
    }
  }'

curl -X POST https://mcp.contio.ai/mcp \
  -H "Authorization: Bearer cto_pat_v1_..." \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id-from-previous-response>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Per-client configuration examples¶

Every MCP client sends the same Authorization header, but the config shape differs. The value must always be Bearer <token> — not Bearer: <token> and not the bare token string. In the JSON snippets below, transport: "http" is the client-side name for the MCP streamable-http transport used by the gateway.

{
  "mcpServers": {
    "contio": {
      "url": "https://mcp.contio.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer cto_pat_v1_<your-token>"
      }
    }
  }
}

devin mcp add contio https://mcp.contio.ai/mcp

{
  "mcpServers": {
    "contio": {
      "url": "https://mcp.contio.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer cto_pat_v1_<your-token>"
      }
    }
  }
}

curl -X POST https://mcp.contio.ai/mcp \
  -H "Authorization: Bearer cto_pat_v1_..." \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example", "version": "1.0.0"}
    }
  }'

Session affinity and cookies¶

The hosted gateway runs more than one task. To keep a stateful session on the same task, the gateway uses cookie-based sticky sessions in addition to the mcp-session-id header. Your HTTP client must preserve and resend the AWS ALB sticky-session cookie on every request if you want live contio-events through the MCP gateway.

Not all MCP SDK clients do this by default — the official Node SDK uses raw fetch and does not store or send cookies. With those clients, the gateway still works:

• Tool calls are handled statelessly, one request at a time, with no cookie required.
• Live events through contio-events require the sticky cookie.

Choosing a live-event delivery option¶

Pick the option that matches your client and infrastructure:

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.

We plan to remove this cookie dependency with a distributed-session architecture. Until then, use the option above that matches your runtime.

Subscribing to contio-events¶

The hosted MCP gateway exposes workspace events as an MCP resource at mcp://contio/events, not as a tool. To receive live events:

1. Complete the initialize handshake.
2. Call resources/subscribe with the resource URI.
3. Keep the streamable-http SSE stream open to receive notifications/resources/updated.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/subscribe",
  "params": {
    "uri": "mcp://contio/events"
  }
}

When the gateway receives a workspace event, it sends a notification like:

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "mcp://contio/events"
  }
}

Call resources/read with the same URI to fetch the latest event payload. You can also call resources/read without subscribing to see the most recent event at any time.

Idempotent tool calls¶

Mutating tools (createMeeting, createActionItem, addMeetingParticipants, etc.) support the Idempotency-Key argument. If you provide one, the Contio API replays the original 2xx response when the same key is reused with the same payload, so retries are safe.

• If you do not supply Idempotency-Key, the hosted gateway automatically generates one for supported operations. The same key is reused across the gateway's internal 5xx/network retries, so a transient upstream failure does not accidentally run the mutation twice.
• If you supply your own Idempotency-Key, the gateway forwards it unchanged. Reuse the same key if your MCP client retries the tool call from its side.

See the Reliability guide for retry behavior and the Errors guide for idempotency error codes.

Scopes¶

The hosted gateway requests these User API scopes during OAuth:

• meetings:read
• meetings:write
• action-items:read
• action-items:write
• calendar:read
• workspace:read
• workspace:write

PATs are created with the subset you choose, so the gateway only registers tools your grants allow.

Admin tools¶

If your token belongs to a workspace owner or admin — or carries the workspace:write scope — the gateway also registers tools from admin-mcp.json for workspace management. Regular user tokens only see the user-level tools.

MCP client OAuth compatibility¶

The hosted MCP gateway supports two ways to authenticate:

• OAuth 2.1 + PKCE — interactive sign-in for Contio-owned first-party desktop agents and CLIs.
• Bearer token — a Personal Access Token (PAT), ideal for third-party agents and MCP clients that do not support Dynamic Client Registration.

Some MCP clients require the server to support Dynamic Client Registration, which lets the client register itself automatically during setup. Contio's hosted MCP gateway does not currently support this registration step, so those clients may show an error like "This server did not advertise a supported OAuth flow" when you try to connect.

Use a Bearer token instead¶

If you see that error, use a PAT:

1. Create a PAT in the Contio app under Settings > Personal Access Tokens. PATs start with cto_pat_v1_ and cannot be minted through the API.
2. In your MCP client, add the server URL:

   https://mcp.contio.ai/mcp
   

3. When the client asks how to authenticate, choose Bearer token or Authentication header and enter:

   Bearer cto_pat_v1_<your-token>
   

The gateway will introspect the token and expose only the tools allowed by the token's scopes.

If your client does not support Bearer-token auth and requires OAuth, let us know through support or your account team so we can prioritize Dynamic Client Registration support.

Self-hosting your own MCP server¶

If you are on a FREE plan or need a private instance inside your own infrastructure, you can build your own MCP server using the same published manifests:

• mcp.json — user-level tools
• admin-mcp.json — workspace admin tools
• operations.json — per-operation metadata (parameters, body schema, scopes)

Call the underlying /v1 endpoints at https://api.contio.ai/v1 with your PAT or OAuth token. Because the /v1 endpoints are available to every plan, a FREE workspace can use them directly. See the Agent Integration guide for how to consume the manifests and a comparison of the available artifacts.

Next steps¶

• Authentication (OAuth 2.1 + PKCE)
• Personal Access Tokens
• Agent Integration
• API Reference