MCP server¶
An AI assistant can manage a tenant of the runtime through the Model Context Protocol:
create services, deploy code, read logs, set secrets, mint narrower tokens. The endpoint is POST /mcp on the control
listener; 21ci mcp bridges it to stdio for clients that cannot connect to a URL.
Every tool is a call to the control API made with the key that connected, so scopes, project and environment restrictions,
quotas, validation, ETags and audit are exactly the API's. Nothing in /mcp can do what the same key cannot do with
curl.
Give the assistant its own key¶
Do not hand an assistant your own key or the operator token (the endpoint refuses it). Make a key for it with only what
it needs and an expiry. With the CLI (token, needs keys:write):
21ci token create --name claude --scopes services:read,services:write,deploy,logs:read --expires-in 30d
# Secret: rtk_01M4Q2GB5APYBGEPYPBX1X4ZYJ_… (shown once)
The operator can create the first key with 21ci key create --tenant ten_… --scopes … (add keys:write to let that key
create further tokens). The scopes decide which tools exist for the assistant:
| Use | Scopes |
|---|---|
| Read-only: look at services, versions, limits | services:read |
| Deploy to existing services | services:read, deploy |
| Deploy and debug | services:read, deploy, logs:read |
| Create and configure services, projects | services:read, services:write, deploy, logs:read, env:write, secrets:write |
| Hand out narrower tokens | add keys:write |
Limit a key to one project (--project prj_…) and, if needed, to some environments (--environment production) when the
assistant works on one app: it then sees and touches only the services of those projects and environments. A key can
only create keys that hold at most its own scopes, projects, environments and lifetime
(self-service keys).
Connect a client¶
The URL is <control API>/mcp, for example https://api.example.com/mcp or http://127.0.0.1:8081/mcp. The key goes in
an Authorization: Bearer header. Keep the key in an environment variable or a file with mode 0600, not in a file you
commit.
Claude Code¶
export RT_KEY=rtk_…
claude mcp add --transport http 21cloud https://api.example.com/mcp --header "Authorization: Bearer $RT_KEY"
claude mcp list # 21cloud: connected
Or in .mcp.json (shared with a team; the key stays in each person's environment):
{
"mcpServers": {
"21cloud": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${RT_KEY}" }
}
}
}
Cursor¶
~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"21cloud": {
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${env:RT_KEY}" }
}
}
}
Claude Desktop and other clients that start a program¶
Claude Desktop starts MCP servers as local programs (its custom connectors can also take request headers in plans that
enable them). Use the bridge. Desktop apps start programs with a minimal PATH, so give the absolute path of 21ci
(which 21ci). Edit claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):
{
"mcpServers": {
"21cloud": {
"command": "/usr/local/bin/21ci",
"args": ["mcp"],
"env": { "RT_API": "https://api.example.com", "RT_KEY": "rtk_…" }
}
}
}
To keep the key out of that file, store it once in the CLI's own config (mode 0600) and drop env:
21ci config set-context assistant --api https://api.example.com --token rtk_… && 21ci config use-context assistant
RT_API is the control API base, without /mcp. The same entry works for any client that runs a stdio MCP server
(Cursor, Zed, Windsurf, Cline, …). Clients with no custom-header support at all can use npx mcp-remote
https://api.example.com/mcp --header "Authorization: Bearer ${RT_KEY}" instead.
Tools¶
tools/list returns only the tools the key's scopes allow, in a fixed order; calling any other is a tool error
insufficient_scope that names the missing scopes. Arguments are checked: an unknown argument is an error naming the ones
the tool takes. service is a slug or a svc_… id (a slug is looked up with services:read).
| Tool | Scopes | What it does | Hints |
|---|---|---|---|
whoami |
any | Tenant, key, scopes, project_ids, environments (null = all) and plan of the key |
read-only |
get_limits |
any | Plan limits and what is left today: invocations, egress, storage, services, schedules | read-only |
list_schedules |
services:read |
Pending one-off schedules of a service (made by std:schedule): id and run_at (limit, cursor) |
read-only |
list_projects |
services:read |
Projects with their environments (limit, cursor) |
read-only |
create_project |
services:write |
slug, name?, environments? |
creates |
list_environments |
services:read |
Environments of a project | read-only |
list_sdks |
services:read |
The operator SDKs the key's grants allow (project?, environment?) and the release each runs |
read-only |
get_sdk_contract |
services:read |
The TypeScript contract (.d.ts) of an SDK the key may use (name, project?, environment?) |
read-only |
list_services |
services:read |
Compact list; filter by project, environment, slug (limit, cursor) |
read-only |
get_service |
services:read |
Full configuration, effective limits, live version, build and admission state, etag |
read-only |
create_service |
services:write |
slug, runtime, name?, project?, environment?, profile?, access? and config blocks |
creates |
update_service |
services:write |
Change fields; a config block replaces that block; etag guards against a concurrent change |
idempotent |
delete_service |
services:write |
Delete a service and its versions, env, secrets; data too unless keep_data |
destructive |
deploy_code |
deploy |
Upload and (by default) activate: source (one TypeScript or JavaScript file) or files (path to text, entry, imports), activate?, close_sockets? (close the service's WebSockets with 1012; by default they stay), compile? |
creates (a version per call) |
list_versions |
services:read |
Versions with build state, and the live one | read-only |
list_objects |
services:read |
Objects holding open WebSockets (with their count) and, for a durable service, objects with storage (prefix, limit, cursor) |
read-only |
list_sockets |
services:read |
Open WebSockets of one object (default default): id, tags, subprotocol, times, buffered bytes, client address (tag, limit, cursor) |
read-only |
close_socket |
sockets:write |
Close one socket (socket), or every socket of an object with a tag; code 1000 or 3000-4999, reason. Audited |
destructive |
rollback |
deploy |
Make version live, or by default the newest older usable one; close_sockets? as in deploy_code |
idempotent |
get_logs |
logs:read |
Recent records with filters (since, until, level, kind, task_id, limit ≤ 200, cursor) |
read-only |
get_stats |
logs:read |
Counts, error rate, latency percentiles and queueing state over 5m, 1h or 24h |
read-only |
set_env |
env:write, services:read |
Merge vars into the service's variables, remove unset; replace: true replaces all |
idempotent |
set_secret |
secrets:write |
Write one secret; the value is never echoed or readable | idempotent |
list_tokens |
keys:write |
The tenant's live keys, never their secrets | read-only |
create_token |
keys:write |
A key with at most the caller's scopes, projects, environments and lifetime (project_ids, environments narrow it); the secret is in the result, once |
creates |
revoke_token |
keys:write |
Revoke a key at once | destructive |
deploy_code sends source as application/typescript (or text/javascript with content_type) and files as the
application/json bundle {entry, files, imports?} (see Deploy input), up to 3 MiB per call. The
upload is validated synchronously: a program that does not parse comes back as validation_failed with
details.diagnostics (file, line, col, message) for the assistant to fix. WASM components are binary: deploy them
with 21ci push.
Not exposed as tools: schedules (only the read-only pending one-off listing, list_schedules), queues, custom hosts, service data export, dropping a durable object's storage, tenants and nodes. Use the API or the CLI.
Results and errors¶
A tool result carries the JSON twice, as structuredContent and as the text of the one content block. Lists are small and
paged; a result over 100 KiB is replaced by a result_too_large error telling the model to narrow the query. A failure is
a normal result with isError: true; its text is <code>: <message> with the control API's error code
(not_found, validation_failed, limit_exceeds_plan, precondition_failed, insufficient_scope, quota_exceeded,
…) and structuredContent.error has code, message and details, so the model can correct itself. Only a malformed
message, an unknown tool or an unknown method is a JSON-RPC error.
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"deploy_code","arguments":{"service":"hello","source":"export default () => new Response('hi')"}}}
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"version\":3,\"source_digest\":\"sha256:…\",\"build_state\":\"pending\",\"service\":\"svc_…\",\"activated\":true}"}],"structuredContent":{"version":3,"source_digest":"sha256:…","build_state":"pending","service":"svc_…","activated":true},"isError":false}}
Transport¶
Streamable HTTP, JSON answers only.
| Topic | Behavior |
|---|---|
| Auth | Authorization: Bearer rtk_… (or x-rt-key). Missing, wrong, revoked or expired: 401 with WWW-Authenticate: Bearer error="invalid_token" and no resource_metadata, so clients ask for a token instead of starting OAuth; the /.well-known/oauth-* documents do not exist. The operator token: 403. Repeated failures from one client are rate-limited like the rest of the control API (429) |
| Origin | A request without Origin (every native client) passes. With one, only a loopback origin (localhost, 127.0.0.0/8, ::1) passes; any other is 403, before the key is looked at. Browser clients on other origins are not supported |
| Methods | POST only. GET, DELETE and the rest: 405 with Allow: POST: there is no server-initiated stream and no session (Mcp-Session-Id is never issued) |
| Messages | One JSON-RPC message per POST. A request gets 200 with Content-Type: application/json; a notification or a response from the client gets 202 and no body. Batches (arrays) and bad JSON are 400 (-32600, -32700); a body over 4 MiB is 413. Accept is not enforced |
| Statelessness | Each request stands alone and re-authenticates, so a revoked key stops working on the next request, with no sessions to expire |
Protocol versions¶
The server answers both revisions in use:
- Handshake era, 2024-11-05 to 2025-11-25 (Claude Code, Claude Desktop, Cursor and the TypeScript SDK use it today).
initializeechoes a version the server speaks (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) and answers 2025-11-25 to any other; the only capability istools(listChanged: false).notifications/initializedandpingwork.MCP-Protocol-Version, when sent on a request afterinitialize, must name one of those versions (400otherwise);initializeitself ignores the header (the version is negotiated in its body). Without it 2025-03-26 is assumed. - Stateless era, 2026-07-28. No handshake: a request carries
params._meta["io.modelcontextprotocol/protocolVersion"], and the HTTP headersMCP-Protocol-Version,Mcp-Methodand (fortools/call)Mcp-Namemust repeat the version, method and tool name of the body, else400with the JSON-RPC error-32020(HeaderMismatch).server/discoverreturns the supported versions (supportedVersions), capabilities andserverInfo(also without_meta). Results carryresultType: "complete". An unsupported version is400with-32022anddata.supported.pingdoes not exist in this revision (404,-32601).
Unknown methods (resources/list, prompts/list, …) are -32601: the server offers tools only.
Notes¶
- Tool calls are audited like the API calls they make:
deploy,service.created,secret.written,key.created, …, with the connecting key as the actor. Secret values never appear in an event or a result. - Treat what an assistant reads (logs, a service's config, the output of a guest) as untrusted text that may try to
instruct it. A key with few scopes and an expiry bounds the damage;
delete_serviceandrevoke_tokenare marked destructive so clients ask for confirmation. - Tool calls count against the same plan quotas and rate limits as the equivalent API calls (
builds_per_hour,max_services, …); a refusal comes back asisErrorwith the API's code. - Source:
crates/rt-api/src/mcp/(mod.rsthe transport,tools.rsthe tools). The endpoint is a thin layer over the/v1router, which it calls in-process with the caller's credentials.