Cluvia API — MCP server

Drive your Cluvia companies from Claude Code, Cursor, VS Code or any other Model Context Protocol (MCP) client: list your companies, give agents tasks, read what they produced, decide approvals, schedule recurring work and grow the team.

1. Overview #

Cluvia runs AI companies: each company has a team of AI agents (a CEO, marketers, writers, website builders and more) that do real work — research, writing, websites — on Cluvia's servers. The Cluvia MCP server is the programmatic door to the same account you use in the app. Anything that speaks MCP can connect to it with a personal access token and act on your behalf.

With it you can:

• See your companies — their teams, open tasks, recent outputs and how many approvals are waiting (list_companies, get_company).
• Give an agent work and wait for the result (assign_task, wait_for_run, run_status). A task whose title asks for a website builds one.
• Read outputs — the deliverables and websites your agents produced (list_outputs, get_output).
• Decide approvals — publishing a site, sending an email reply, starting or finishing an A/B test, a connected-tool call (list_approvals, approve, deny).
• Schedule recurring work with a cron expression in your time zone (list_schedules, create_schedule, delete_schedule).
• Shape the team — hire from the role library and set each agent's standing policy for outside actions (hire_agent, set_policy).

The server exposes 15 tools. It does not expose prompts or resources. A typical session: list_companies for a companyKey, get_company for the team, assign_task to give an agent work, then wait_for_run for the result. Runs start on Cluvia's servers within seconds when there is room, use your plan's credits, and appear on the app's task board when they finish.

The server also sends these instructions to your client when it connects, so your AI assistant knows how to start:

Cluvia runs AI companies whose agents do real work. Start with list_companies for a companyKey and get_company for the team, then assign_task to give an agent work and wait_for_run for the result. Runs start on Cluvia's servers within seconds when there is room. hire_agent is queued and applies within about a minute (by the Cluvia app when it has that company open, or by Cluvia when nobody does); set_policy applies at once.

2. Quick start #

Step 1: create an access token

1. Sign in to Cluvia at www.usecluvia.com.
2. Open Connections in the sidebar.
3. In the panel Connect Claude Code, Cursor or Claude Desktop, give the token a name (for example “My laptop”).
4. Tick the Permissions it needs. The default, Read and Run tasks, is enough for this quick start. Add Approve and perform to decide approvals and Administer to hire agents or set policies (see permissions).
5. Leave Company on All companies, or pick one company to limit the token to it.
6. Click Create token. The token (cluvia_pat_ followed by 32 letters and digits) is shown once, with ready-made setup snippets. Copy it now.

Step 2: add the server to Claude Code

claude mcp add --transport http cluvia https://mcp.usecluvia.com/mcp --header "Authorization: Bearer cluvia_pat_YOUR_TOKEN"

Replace cluvia_pat_YOUR_TOKEN with your token. Check the connection with claude mcp list, or with /mcp inside a Claude Code session. Other clients are covered in Connecting your client.

Step 3: make a first call

Ask your assistant in plain words. It picks the tools.

Prefer raw HTTP? The same first call with curl:

curl -sS https://mcp.usecluvia.com/mcp \
  -H "Authorization: Bearer $CLUVIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_companies","arguments":{}}}'

3. Endpoint and transport #

Endpoint

POST https://mcp.usecluvia.com/mcp

The path is exactly /mcp. The earlier address, https://companyos-ai-proxy.adamidrissi177.workers.dev/mcp, is the same server and keeps working, so existing client configurations do not need to change. New setups should use https://mcp.usecluvia.com/mcp.

The host mcp.usecluvia.com serves only the MCP endpoint. Opening https://mcp.usecluvia.com/ (or any other path) in a browser redirects to this page; paths under /.well-known/ and requests other than GET or HEAD to any path but /mcp answer 404.

Transport

• Streamable HTTP, request–response only. Send one JSON-RPC 2.0 message per POST. Every answer is a single JSON object with Content-Type: application/json and Cache-Control: no-store. The server never opens a Server-Sent Events stream, so the Accept header does not change the answer.
• No sessions. The server issues no Mcp-Session-Id; every request stands alone and must carry the Authorization header.
• No batches. A JSON array is refused with HTTP 400.
• Request body limit: 64 KB. Larger bodies get HTTP 413.
• GET, DELETE, OPTIONS and every method other than POST get HTTP 405 with Allow: POST. There is no stream to open with GET and no session to end with DELETE.
• Notifications (messages without an id, such as notifications/initialized or notifications/cancelled) are accepted with HTTP 202 and no body. Responses a client sends (messages with result or error and no method) also get 202. The server never sends requests or notifications to the client.
• Headers MCP-Protocol-Version, Mcp-Method and Mcp-Name are informational. A request is never refused because of them; the protocol version is read from the message body (below).
• Browsers: a request carrying an Origin header from another website is refused with HTTP 403 (a guard against DNS rebinding). The endpoint sends no CORS headers. Call it from an MCP client, a script or a server, not from a web page.

Protocol versions

Supported MCP protocol versions, newest first:

How the version is chosen:

• Only params._meta["io.modelcontextprotocol/protocolVersion"] in the request body decides. If it is missing, the request is served in the earlier shape and is never refused for that.
• If it is 2026-07-28, the request is served in the current shape. Any other supported version gets the earlier shape.
• If it is present but not a supported version, the server answers HTTP 400 with JSON-RPC error -32022 "Unsupported protocol version" and data: { "supported": [...], "requested": ... }.
• initialize answers with the protocolVersion the client asked for when it is 2025-11-25, 2025-06-18 or 2025-03-26, and with 2025-11-25 otherwise.

Methods

serverInfo is { "name": "cluvia", "title": "Cluvia", "version": "1.0.0", "websiteUrl": "https://www.usecluvia.com/developers" }. websiteUrl is left out for 2025-06-18 and 2025-03-26, whose schemas do not define it. Authentication is checked before the body is read, so even initialize needs a valid token.

Example: initialize

Request:

POST /mcp HTTP/1.1
Host: mcp.usecluvia.com
Authorization: Bearer cluvia_pat_YOUR_TOKEN
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "cluvia", "title": "Cluvia", "version": "1.0.0" },
    "instructions": "Cluvia runs AI companies whose agents do real work. Start with list_companies for a companyKey and get_company for the team, then assign_task to give an agent work and wait_for_run for the result. ..."
  }
}

(A client asking for 2025-11-25 also gets "websiteUrl": "https://www.usecluvia.com/developers" in serverInfo.) Then send the notifications/initialized notification (answered with 202) and call tools/list.

Example: a 2026-07-28 request

Clients on 2026-07-28 name the version in _meta on each request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "list_companies",
        "title": "List companies",
        "description": "List the companies in this Cluvia account: name, industry, team size and open tasks. Each has a companyKey the other tools take.",
        "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
        "annotations": { "readOnlyHint": true, "openWorldHint": false }
      }
    ],
    "_meta": {
      "io.modelcontextprotocol/serverInfo": { "name": "cluvia", "title": "Cluvia", "version": "1.0.0", "websiteUrl": "https://www.usecluvia.com/developers" }
    }
  }
}

(The real answer lists every tool your token may call; one is shown.)

Tool results

A successful tools/call returns the data twice: as pretty-printed JSON text in content[0].text, and as an object in structuredContent.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\n  \"companies\": [ ... ]\n}" }],
    "structuredContent": { "companies": [ ... ] },
    "isError": false
  }
}

A tool that cannot do what was asked returns a normal result with isError: true and a readable sentence, and no structuredContent. The HTTP status is 200. Your assistant can read the sentence and correct itself.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "No company has the companyKey \"company-x:2026-01-01T00:00:00.000Z\" — call list_companies for the keys." }],
    "isError": true
  }
}

Every tool's input schema sets additionalProperties: false. Read-only tools carry the annotations { "readOnlyHint": true, "openWorldHint": false }; the others list their own annotations below.

4. Authentication #

Every request needs a personal access token in the Authorization header:

Authorization: Bearer cluvia_pat_YOUR_TOKEN

The word Bearer followed by one space is required, with that capitalisation.

Personal access tokens

• Create: in the app, Connections → Connect Claude Code, Cursor or Claude Desktop → Create token (steps in Quick start). Token management needs a signed-in app session: a token cannot create, list or revoke tokens.
• Format: cluvia_pat_ followed by 32 base62 characters (0-9, A-Z, a-z), for example cluvia_pat_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56 (not a real token).
• Shown once: Cluvia stores only a SHA-256 hash of the token, so it cannot show it again. The token list shows its name, the first characters (cluvia_pat_XXXX…), its permissions and when it was last used.
• Limit: up to 10 live tokens per account.
• Expiry: tokens do not expire. Revoke a token you no longer use.
• Revoke: click the trash icon next to the token on the Connections page. It stops working on the next request.
• No plan requirement: every plan, Free included, can create tokens and use the MCP server. What a call may spend is governed by your plan (see Plans and credits).

Permissions

Each token carries one or more permissions. They are independent: Administer does not include Read. The app ticks Read and Run tasks for a new token; change the ticks before you create it. tools/list shows only the tools a token may call.

Calling a tool without its permission returns an isError result and does nothing (it does not count toward the rate limit):

This access token doesn't have the "admin" permission this needs. Create a token that has it on the Connections page in Cluvia.

Tokens created before permissions existed act as the whole account and appear in the app as Full access (legacy). Replace them with a token that has only the permissions you need.

Company-limited tokens

• A token limited to one company reaches only that company. list_companies returns just that one.
• Any other company answers exactly like a company that does not exist: No company has the companyKey "…" — call list_companies for the keys.
• Runs, approvals and schedules are judged by the company they belong to: another company's run answers No run "…" in this account., its approval Approval not found., its schedule Schedule not found.
• Cluvia's site-management routes, which the app uses, refuse a one-company token any site that is not bound to its company (the app warns: “One-company tokens can't publish or manage sites.”). Over MCP, such a token with Approve and perform can still approve a publish_site approval of its own company.
• Deleting the company revokes every token limited to it. Account-wide tokens are not affected.
• Deleting your account deletes all of its tokens.

What a refused request looks like

Authentication failures are answered at the HTTP level, before the message is read, with a JSON-RPC error body (code -32600, no id). A 401 also carries WWW-Authenticate: Bearer realm="cluvia".

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer realm="cluvia"

{"jsonrpc":"2.0","error":{"code":-32600,"message":"This access token is not valid — it may have been revoked. Create a new one on the Connections page in Cluvia."}}

There is no OAuth: the server publishes no OAuth or protected-resource metadata, and a token is the only way for an outside tool to sign in. (The app's own sign-in session also works as a bearer, with every permission, but outside tools should use a token.)

5. Connecting your client #

Any MCP client that supports the Streamable HTTP transport and lets you set a request header can connect. Each client writes its configuration a little differently; the snippets below follow each client's own documentation. In every snippet, replace the token placeholder with yours, or keep it in an environment variable as shown.

Claude Code

claude mcp add --transport http cluvia https://mcp.usecluvia.com/mcp --header "Authorization: Bearer cluvia_pat_YOUR_TOKEN"

• Add --scope user to use the server in every project, or --scope project to share it through the project's .mcp.json. The default scope is local.
• Check it with claude mcp list, claude mcp get cluvia, or /mcp in a session.
• In a shared .mcp.json, keep the token out of the file with an environment variable:

{
  "mcpServers": {
    "cluvia": {
      "type": "http",
      "url": "https://mcp.usecluvia.com/mcp",
      "headers": { "Authorization": "Bearer ${CLUVIA_TOKEN}" }
    }
  }
}

Reference: Claude Code MCP documentation.

Cursor

Add the server to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "cluvia": {
      "url": "https://mcp.usecluvia.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLUVIA_TOKEN}" }
    }
  }
}

The snippet the Cluvia app shows after you create a token also includes "type": "http"; Cursor's documentation shows remote servers without it, and the form above follows Cursor's documentation. Reference: Cursor MCP documentation.

VS Code

VS Code's own format uses a top-level servers key (not mcpServers) and requires type. Put this in .vscode/mcp.json in a workspace, or in your user configuration (command MCP: Open User Configuration). The inputs entry makes VS Code prompt for the token instead of keeping it in the file. The tools are then available in VS Code's Chat:

{
  "inputs": [
    { "type": "promptString", "id": "cluvia-token", "description": "Cluvia access token", "password": true }
  ],
  "servers": {
    "cluvia": {
      "type": "http",
      "url": "https://mcp.usecluvia.com/mcp",
      "headers": { "Authorization": "Bearer ${input:cluvia-token}" }
    }
  }
}

References: Add and manage MCP servers in VS Code, MCP configuration reference.

Windsurf

Windsurf's MCP documentation now lives on docs.devin.ai, where the product is called Devin Desktop. Remote servers are written with serverUrl. The file is ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows); if your version reads a different file, open it from the editor's MCP settings.

{
  "mcpServers": {
    "cluvia": {
      "serverUrl": "https://mcp.usecluvia.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLUVIA_TOKEN}" }
    }
  }
}

Claude Desktop and Claude.ai

Claude Desktop and Claude.ai add remote servers as custom connectors (Customize → Connectors → Add custom connector on Free, Pro and Max, or Organization settings → Connectors for Team and Enterprise owners).

• If your organization has custom request headers for connectors (Anthropic offers this to a limited set of organizations): choose authentication No sign-in, then under Request headers add authorization with the full value Bearer cluvia_pat_YOUR_TOKEN.
• Otherwise, custom connectors sign in with OAuth or not at all. Cluvia does not offer OAuth yet, so a custom connector cannot connect to Cluvia today. Use Claude Code, or the local bridge below.

Local bridge for Claude Desktop. Claude Desktop's claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\) runs local servers. The community tool mcp-remote (not made by Cluvia or Anthropic; needs Node.js) bridges a local entry to a remote server:

{
  "mcpServers": {
    "cluvia": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.usecluvia.com/mcp", "--header", "Authorization:${AUTH_HEADER}", "--transport", "http-only"],
      "env": { "AUTH_HEADER": "Bearer cluvia_pat_YOUR_TOKEN" }
    }
  }
}

The header value goes in env because some clients (Claude Desktop on Windows among them) do not pass spaces inside args correctly. --transport http-only matches Cluvia, which has no SSE stream. References: Claude custom connectors, MCP: connect to remote servers.

Any other MCP client

Use these settings:

Many clients read the common mcpServers JSON form:

{
  "mcpServers": {
    "cluvia": {
      "type": "http",
      "url": "https://mcp.usecluvia.com/mcp",
      "headers": { "Authorization": "Bearer cluvia_pat_YOUR_TOKEN" }
    }
  }
}

A client that only speaks the older SSE transport, or only stdio, needs a bridge such as mcp-remote (above).

6. Concepts #

Companies and companyKey

Your account holds one or more companies. Every tool that works on a company takes a companyKey, a string built from the company's id and creation time, for example company-7f3a9e2b:2026-09-01T09:30:00.000Z. Get it from list_companies and pass it back unchanged; treat it as opaque. Companies are read from your cloud workspace, the same data the app shows.

Agents

Each company has a team of agents, each with an id, name, role, department and status (working while one of its tasks runs, online, or idle). Tools that take an agent accept:

1. the agent's exact id; otherwise
2. a role or name, matched case-insensitively and exactly ("content writer" matches “Content Writer”). If several agents match, active agents are preferred, and exactly one must remain. Otherwise the tool answers Several agents match "…": … Pass an agent id.

Inactive or retired agents can still be matched, but a run given to one fails when it starts (error code agent_missing). Use ids from get_company to be exact.

Tasks and runs

assign_task creates a run: one piece of work by one agent. Runs started over MCP have origin: "mcp" and taskId: null; the app adds the task to its board when the run finishes. A run starts within seconds when there is room. When your plan's tasks at once are in use, or Cluvia is busy, it waits its turn. A run still running 15 minutes after it starts is stopped and fails with error code stale.

Run modes. assign_task picks the mode from the title and brief, checking in this order:

• experiment — the title says “A/B test”, “AB test” or “split test”; or it says experiment or variant together with run, start, launch or test, and a page word (page, site, website, headline, hero, button, CTA, pricing, sign-up) appears in the title or brief. The run proposes an A/B test of one page of the company's live site.
• website — the title names a site (website, web app, webpage, landing page, home page, marketing site, micro site, “the site”), or pairs a build verb (build, create, make, design, develop, ship, launch, prototype, code, implement, redesign, rebuild) with an app, tool, tracker, calculator, to-do, game, dashboard, prototype or MVP. The run builds a website.
• deliverable — everything else: a written result such as research, a plan, an email or a post.

Error codes on a failed run (run.errorCode): cut_off, narration_only, website_cut_off, cost_cap, task_error, nothing_to_review, proposal_live, key, company_missing, draft, provider_down, stale, workspace_unavailable, agent_missing, credits_exhausted. run.error always carries a readable explanation. Common ones when a run starts:

Outputs

An output is something an agent produced: a deliverable (text) or a website. Outputs live in the company and are listed by get_company (latest 10) and list_outputs. A deliverable that used web research ends with a ranked source list:

…the deliverable text…

Sources:
1. Example source title — https://example.com/article
2. Another source — https://example.org/page

For a website, the API returns its file names, never the raw HTML.

Approvals

Actions that reach outside Cluvia wait for your decision unless you have told the agent otherwise. A pending approval lapses after 7 days. Kinds:

When a website run finishes, the agent's publish_site policy decides: deny publishes nothing, allow publishes without asking, and ask (the default) creates a publish_site approval.

Policies

A policy is an agent's standing rule for one kind of action, set with set_policy. It applies at once. A kind with no policy set is treated as ask, which for web and images means allowed.

Schedules

A schedule gives an agent the same task each time a cron expression comes round in a time zone. Each slot queues a run with origin: "schedule" and spends credits. A slot is skipped (with the reason recorded) when the plan has no autonomous schedules, the daily run limit or the plan's scheduled-runs-per-day limit is reached, credits run out, the company's spend limit is reached, or the company was switched off or deleted. Schedules need a paid plan. An account can keep up to 100 schedules.

Cron syntax: exactly five fields — minute (0–59), hour (0–23), day of month (1–31), month (1–12), day of week (0–7, where 0 and 7 are Sunday). Supported: *, lists (1,15), ranges (1-5) and steps (*/15, 0-30/10, 5/10). Not supported: names (MON, JAN), macros (@daily) or seconds. When both day fields are restricted, a day matches if either matches. Examples: 0 9 * * 1 (Mondays at 09:00), 30 8 * * 1-5 (weekdays at 08:30), 0 */6 * * * (every six hours).

Team changes and hiring

The team lives in the company document that the app edits, so hire_agent does not change it directly. It queues a hire, which is applied within about a minute: by the Cluvia app if it has the company open, or by Cluvia's servers when nobody does. The answer's note says which applies. Checks that can be made when queuing (role in the library, role limit, team size, company not in planning) are made then, so most refusals come back at once. If the token is revoked or loses Administer before the hire applies, the hire is withdrawn. Up to 100 changes can wait per account.

Plans, credits and limits

Calls that start work run through the same checks as the app: your plan's daily run limit, how many tasks may run at once, and your credits. The defaults per plan:

• These are the standard plan limits. Your current limits are always shown in the app under Settings → Plan.
• Credits: 1 credit = $0.001 of the model cost of a run on Cluvia's key, metered per run and rounded up. While a run is in flight, the credit check sets aside an estimate (500 credits for a written task, 1,250 for a website build); the charge is the metered cost. Paid plans can top up: 200 credits per $1, 220 from $25, 240 from $50, from $1 to $500.
• Your own OpenRouter key (paid plans): the part of a run billed to your key is never metered as credits. The daily run limit and tasks-at-once limit still apply.
• Days for the daily run limit are UTC days.
• The company daily spend limit and the autopilot rules apply to automatic starts only. A task you assign over MCP is not automatic, so they do not apply to it; scheduled runs are subject to the spend limit.
• Over MCP, a plan refusal comes back as an isError result carrying the message (see Plan and credit refusals).

Not available over MCP yet

Cancelling a run, editing a schedule (delete and re-create it instead), and reading an agent's current policies are done in the app. Tokens, billing, settings and your own OpenRouter key are managed only in the signed-in app.

Ids and timestamps

Ids the server creates have the form <prefix>_<32 lowercase hex>: runs run_…, schedules sch_…, approvals apr_…, queued changes cmd_…. Company, agent, task and output ids come from the app; treat every id as an opaque string. Timestamps are ISO 8601 strings in UTC, or null. All ids in the examples on this page are made up.

7. Tools reference #

Each tool lists the permission it needs, its parameters, what it returns (the structuredContent object; content[0].text carries the same JSON as text), its errors (returned as isError results with the exact sentence shown) and its side effects. Every tool can also return the shared errors in Tool errors, such as the rate limit. Example ids are made up.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_companies","arguments":{}}}

{
  "companies": [
    {
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "name": "Sunrise Bakery",
      "industry": "Food and drink",
      "agents": 5,
      "tasks": 3
    }
  ]
}

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_company","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z"}}}

{
  "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
  "name": "Sunrise Bakery",
  "industry": "Food and drink",
  "mission": "Fresh bread for the neighbourhood, ordered online.",
  "agents": [
    { "id": "agent-1a2b3c", "name": "Maya", "role": "CEO", "department": "Executive", "status": "idle", "active": true },
    { "id": "agent-4d5e6f", "name": "Theo", "role": "Content Writer", "department": "Marketing", "status": "working", "active": true }
  ],
  "openTasks": [
    { "id": "task-77ab", "title": "Write the spring menu page copy", "status": "running", "assigneeId": "agent-4d5e6f", "assignee": "Content Writer", "brief": null }
  ],
  "recentOutputs": [
    {
      "id": "output-91c2",
      "title": "Competitor price check",
      "agentId": "agent-1a2b3c",
      "agent": "CEO",
      "taskId": "task-5c3d",
      "generatedAt": "2026-10-06T14:02:11.000Z",
      "excerpt": "Three bakeries within two miles sell sourdough between £3.20 and £4.50…",
      "website": false
    }
  ],
  "pendingApprovals": 1
}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_outputs","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z","limit":2}}}

{
  "outputs": [
    {
      "id": "output-a410",
      "title": "Spring menu landing page",
      "agentId": "agent-8e9f0a",
      "agent": "Website Builder",
      "taskId": "task-61fe",
      "generatedAt": "2026-10-07T08:15:40.000Z",
      "excerpt": "Spring menu landing page with opening hours and an order form.",
      "website": true
    },
    {
      "id": "output-91c2",
      "title": "Competitor price check",
      "agentId": "agent-1a2b3c",
      "agent": "CEO",
      "taskId": "task-5c3d",
      "generatedAt": "2026-10-06T14:02:11.000Z",
      "excerpt": "Three bakeries within two miles sell sourdough between £3.20 and £4.50…",
      "website": false
    }
  ],
  "total": 14
}

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_output","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z","outputId":"output-a410"}}}

{
  "id": "output-a410",
  "title": "Spring menu landing page",
  "agentId": "agent-8e9f0a",
  "agent": "Website Builder",
  "taskId": "task-61fe",
  "generatedAt": "2026-10-07T08:15:40.000Z",
  "content": "Spring menu landing page with opening hours and an order form.",
  "website": { "entry": "index.html", "files": ["index.html", "menu.html", "styles.css"] }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "assign_task",
    "arguments": {
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "agent": "Content Writer",
      "title": "Draft a launch email for the spring menu",
      "brief": "Warm, local tone. Under 150 words. Mention the Saturday tasting."
    }
  }
}

{
  "runId": "run_3f9c2a7b1e4d4c0a9b8e7f6a5d4c3b2a",
  "status": "queued",
  "mode": "deliverable",
  "agent": { "id": "agent-4d5e6f", "name": "Theo", "role": "Content Writer" },
  "note": "The run starts within seconds when there is room. Call wait_for_run with this runId for the result."
}

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"run_status","arguments":{"runId":"run_3f9c2a7b1e4d4c0a9b8e7f6a5d4c3b2a"}}}

{
  "run": {
    "id": "run_3f9c2a7b1e4d4c0a9b8e7f6a5d4c3b2a",
    "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
    "taskId": null,
    "agentId": "agent-4d5e6f",
    "agentRole": "Content Writer",
    "title": "Draft a launch email for the spring menu",
    "brief": "Warm, local tone. Under 150 words. Mention the Saturday tasting.",
    "mode": "deliverable",
    "status": "running",
    "scheduleId": null,
    "scheduledFor": null,
    "origin": "mcp",
    "startedAt": "2026-10-07T10:01:03.000Z",
    "finishedAt": null,
    "createdAt": "2026-10-07T10:00:12.000Z",
    "updatedAt": "2026-10-07T10:01:20.000Z",
    "content": null,
    "error": null,
    "costUsd": null,
    "model": null,
    "approvalId": null,
    "progress": { "chars": 412, "phase": "writing" },
    "waitingFor": null,
    "segments": 0,
    "stop": null,
    "acted": null,
    "errorCode": null,
    "startId": null
  },
  "events": [
    { "at": "2026-10-07T10:00:12.000Z", "kind": "queued", "text": "Queued from an outside tool (MCP)." },
    { "at": "2026-10-07T10:01:03.000Z", "kind": "started", "text": "Started (deliverable)." }
  ]
}

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"wait_for_run","arguments":{"runId":"run_3f9c2a7b1e4d4c0a9b8e7f6a5d4c3b2a","timeoutSec":50}}}

{
  "finished": true,
  "waitedSec": 21,
  "run": {
    "id": "run_3f9c2a7b1e4d4c0a9b8e7f6a5d4c3b2a",
    "status": "done",
    "mode": "deliverable",
    "origin": "mcp",
    "finishedAt": "2026-10-07T10:01:44.000Z",
    "content": "Subject: Spring has landed at Sunrise Bakery\n\nHi neighbour,\n\nOur spring menu is here…",
    "error": null,
    "errorCode": null,
    "costUsd": 0.0042,
    "...": "the other run fields, as in run_status"
  },
  "events": [
    { "at": "2026-10-07T10:00:12.000Z", "kind": "queued", "text": "Queued from an outside tool (MCP)." },
    { "at": "2026-10-07T10:01:03.000Z", "kind": "started", "text": "Started (deliverable)." },
    { "at": "2026-10-07T10:01:44.000Z", "kind": "finished", "text": "Finished." }
  ]
}

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"list_approvals","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z"}}}

{
  "approvals": [
    {
      "id": "apr_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "runId": "run_0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
      "agentId": "agent-8e9f0a",
      "agentRole": "Website Builder",
      "kind": "publish_site",
      "summary": "Publish the Sunrise Bakery site",
      "payload": { "runId": "run_0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e", "projectSlug": "sunrise-bakery", "company": "Sunrise Bakery" },
      "status": "pending",
      "createdAt": "2026-10-07T08:16:02.000Z",
      "expiresAt": "2026-10-14T08:16:02.000Z",
      "decidedAt": null,
      "decidedNote": null,
      "decidedBy": null,
      "result": null,
      "updatedAt": "2026-10-07T08:16:02.000Z"
    }
  ],
  "now": "2026-10-07T10:05:00.000Z"
}

{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"approve","arguments":{"approvalId":"apr_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f","note":"Looks good."}}}

{
  "ok": true,
  "approval": {
    "id": "apr_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "kind": "publish_site",
    "status": "approved",
    "decidedAt": "2026-10-07T10:06:30.000Z",
    "decidedNote": "Looks good.",
    "decidedBy": "token:pat_2d4f6a8c0e1b3d5f7a9c1e3b5d7f9a1c",
    "result": { "url": "https://(the site's live address)/", "siteId": "(site id)" },
    "...": "the other approval fields, as in list_approvals"
  }
}

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"deny","arguments":{"approvalId":"apr_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f","note":"Wait for the new photos."}}}

{
  "ok": true,
  "approval": {
    "id": "apr_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "kind": "publish_site",
    "status": "denied",
    "decidedNote": "Wait for the new photos.",
    "...": "the other approval fields, as in list_approvals"
  }
}

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"list_schedules","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z"}}}

{
  "schedules": [
    {
      "id": "sch_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "agentId": "agent-4d5e6f",
      "agentRole": "Content Writer",
      "title": "Write this week's newsletter",
      "brief": "Lead with the weekend specials.",
      "cron": "0 9 * * 1",
      "timezone": "Europe/London",
      "nextRunAt": "2026-10-12T08:00:00.000Z",
      "lastRunAt": "2026-10-05T08:00:00.000Z",
      "enabled": true,
      "createdAt": "2026-09-20T17:44:10.000Z",
      "updatedAt": "2026-10-05T08:00:02.000Z"
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "create_schedule",
    "arguments": {
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "agent": "agent-4d5e6f",
      "title": "Write this week's newsletter",
      "brief": "Lead with the weekend specials.",
      "cron": "0 9 * * 1",
      "timezone": "Europe/London"
    }
  }
}

{
  "schedule": {
    "id": "sch_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
    "agentId": "agent-4d5e6f",
    "agentRole": "Content Writer",
    "title": "Write this week's newsletter",
    "brief": "Lead with the weekend specials.",
    "cron": "0 9 * * 1",
    "timezone": "Europe/London",
    "nextRunAt": "2026-10-12T08:00:00.000Z",
    "lastRunAt": null,
    "enabled": true,
    "createdAt": "2026-10-07T10:10:00.000Z",
    "updatedAt": "2026-10-07T10:10:00.000Z"
  }
}

{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"delete_schedule","arguments":{"scheduleId":"sch_0a1b2c3d4e5f60718293a4b5c6d7e8f9"}}}

{ "ok": true }

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "hire_agent",
    "arguments": {
      "companyKey": "company-7f3a9e2b:2026-09-01T09:30:00.000Z",
      "role": "Growth Marketer",
      "specialization": "Local ads",
      "instructions": "Focus on customers within three miles of the shop."
    }
  }
}

{
  "commandId": "cmd_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "status": "pending",
  "note": "applies within about a minute"
}

{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"set_policy","arguments":{"companyKey":"company-7f3a9e2b:2026-09-01T09:30:00.000Z","agent":"Website Builder","kind":"publish_site","policy":"ask"}}}

{
  "status": "applied",
  "agentId": "agent-8e9f0a",
  "agentRole": "Website Builder",
  "kind": "publish_site",
  "policy": "ask"
}

8. Errors #

There are three layers. Check them in this order: the HTTP status, then a JSON-RPC error, then result.isError.

HTTP and JSON-RPC errors

These come back as a JSON-RPC error object: {"jsonrpc":"2.0","id":…,"error":{"code":…,"message":"…"}} (no id when the request could not be read that far).

Tool errors (isError)

When a tool refuses or fails, the answer is HTTP 200 with a normal result: isError: true and the reason in content[0].text. The tool's own errors are listed in its section. Errors any tool can return:

Plan and credit refusals

Tools that start work (assign_task, create_schedule) are refused with an isError result when a plan limit applies. The server never answers HTTP 429 or 402 on /mcp; only the message comes through.

9. Rate limits and usage #

Being rate limited is an isError result (“Rate limit reached — try again in a minute.”), never HTTP 429. To stay well inside the limit, prefer one wait_for_run with a long timeout over many run_status calls.

10. Security and data #

• A token acts as you. Anything it is permitted to do happens as if you did it in the app, and spends your credits. Give each tool its own token with only the permissions it needs, and limit it to one company where you can.
• Your account only. A token reaches only the account that created it, and a company-limited token only that company. Data from other accounts is never visible.
• Outside actions wait for approval by default. Publishing a site, sending email and similar actions create approvals unless you have set the agent's policy to allow. Only a token with Approve and perform can approve, and approving carries the action out. A connected_tool approval runs only the exact call whose payloadHash you pass.
• Stored safely. Cluvia keeps only a SHA-256 hash of each token. The token is shown once, at creation.
• Revoke at any time on the Connections page; the token stops working on the next request. Queued hires from a revoked token are withdrawn. Deleting a company revokes the tokens limited to it; deleting your account deletes all of your tokens.
• Account checks. On each request the server confirms the token's account can still use Cluvia. That check is cached for up to 10 minutes.
• What a token cannot do: manage tokens, settings, billing, plan checkout or your own OpenRouter key. Those need a signed-in app session.
• Transport. Use HTTPS. Requests from web pages on other sites are refused. Keep tokens in environment variables or your client's secret storage, not in files you commit.
• Data handling is described in the Privacy policy and the Subprocessors list. Use of the API is covered by the Terms.
• Report a security problem to usecluvia@gmail.com. Please include what you found and how to reproduce it, and do not access other people's data.

11. Changelog #

Changes to the MCP server and to this page, newest first.

2026-10-08

Runs start within seconds when there is room (run queue), instead of at the next minute. startedAt can be null for a run's first seconds in running. New event kinds: deferred and requeued.

2026-10-07

Docs published; MCP server available at https://mcp.usecluvia.com/mcp. The earlier workers.dev address keeps working. Server version 1.0.0: 15 tools; protocol versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26.

12. Support #

Questions, bugs or feature requests: usecluvia@gmail.com. Include the tool name, the time of the call (UTC) and the error text, and never send your token.

Back to Cluvia