Skip to content

Agent Integration

Contio publishes a set of machine-readable artifacts alongside the User API docs so that coding agents and LLM toolchains can discover and call the API without hand-coding the integration.

Artifacts

Artifact URL Purpose
llms.txt /user-api/llms.txt Human- and LLM-readable index of every User API operation. Drop this URL into an agent's context window for a quick overview of available endpoints.
operations.json /user-api/agent/operations.json Structured per-operation metadata (parameters, request/response schemas, response headers, auth surface).
mcp.json /user-api/agent/mcp.json Model Context Protocol tool manifest for the standard user-facing operations.
admin-mcp.json /user-api/agent/admin-mcp.json MCP tool manifest scoped to workspace administration operations (requires a workspace API key).

Quick start

Give your coding agent the llms.txt URL and it will have enough context to explore the API, select the right endpoints, and construct valid requests:

https://docs.contio.ai/user-api/llms.txt

Pointing a coding agent at the API

Paste the URL into the agent's prompt or context window:

Read https://docs.contio.ai/user-api/llms.txt and use the
Contio User API to list my upcoming meetings.

Fetch operations.json for enriched per-operation metadata:

curl -s https://docs.contio.ai/user-api/agent/operations.json | jq 'keys'

If the agent supports the Model Context Protocol, register the tool manifest:

import tools from "./mcp.json" assert { type: "json" };

// Return all tools from the manifest
server.setRequestHandler("tools/list", async () => ({ tools: tools.tools }));

What's in llms.txt

The llms.txt file follows the llms.txt standard — a convention for providing LLM-readable context about a site or API. It contains:

  1. Header — Links to related resources (OpenAPI spec, operations.json, mcp.json, admin-mcp.json)
  2. Authentication summary — Operation counts per auth surface
  3. Operations by category — Every operation grouped by domain (Meetings, Action Items, etc.)

llms.txt is for discovery, not execution

llms.txt gives agents enough context to understand what the API can do and select the right operations. For how to call them (schemas, parameter types, auth details), agents should fetch operations.json or the OpenAPI spec.

Two MCP manifests

The User API ships two MCP tool manifests, split by privilege level:

  • mcp.json — standard user operations (meetings, action items, agenda, calendar, participants, tokens). Callable with any valid user credential.
  • admin-mcp.json — workspace-administration operations (manage workspace settings, members, API keys, webhooks). These require a workspace API key (cto_wk_v1_...). PATs, short-lived access tokens and OAuth tokens can't use them, even when they belong to a workspace owner or admin.

Load the manifest that matches the credential your integration uses. Keep the workspace API key and the admin tools out of untrusted contexts.

Each tool in either manifest carries an inputSchema whose properties are all described, and — for operations that return a JSON object on success — an outputSchema describing the structured result. Tools that return no body (204), a primitive, or a file download omit outputSchema.

Choosing an artifact

Use Case Recommended Artifact
Quick exploration with a coding agent llms.txt
Building an HTTP client or code generator operations.json
Building an MCP server (user operations) mcp.json
Building an MCP server (workspace admin) admin-mcp.json
Full schema validation or SDK generation OpenAPI spec

Authentication

Agents still need valid credentials. The User API accepts a ContioAuth bearer token via the Authorization header. Choose a credential based on plan and use case:

  • FREE workspaces: For quick, ad hoc automation, guide the user to create a short-lived access token (cto_slt_v1_...) from Settings > API Tokens. Short-lived tokens are available on all plans, expire within hours, and are shown once at creation. See Authentication.
  • PRO workspaces and higher: For unattended scripts and agents, the simplest option is a Personal Access Token (cto_pat_v1_...):

Authorization: Bearer cto_pat_v1_...
- Interactive, user-consented access: Use the OAuth 2.1 + PKCE flow.

Admin MCP tools need a workspace API key (cto_wk_v1_...) instead. A workspace owner or admin issues it in the Contio app; a user credential can't call admin operations, whatever the user's workspace role.

The auth.surface field in operations.json tells you which surface each operation requires:

Surface Description
user-oauth ContioAuth bearer token (OAuth token or Personal Access Token)
admin Workspace API key (cto_wk_v1_...) sent as a ContioAuth bearer token
public No authentication required (OAuth discovery, health checks)