MCP Cloud

MCP Cloud is Studio's hosted Model Context Protocol endpoint. It lets an external AI agent or IDE -- Claude Desktop, Claude Code, Cursor, or any MCP-capable client -- connect over HTTP and operate directly on a project's content, without running the local @contentrain/mcp server or cloning the repository.

Studio boots a real MCP server on a loopback port at startup and exposes it through an authenticated public proxy. The client speaks plain MCP; Studio handles repository identity, authentication, plan gating, and the merge/review lifecycle on the caller's behalf.

Who is this for?

Teams that want their agents to read and write content over a managed connection -- no local checkout, no GitHub App tokens in the client, no MCP server to run. The connecting client only needs the endpoint URL and a Bearer key.

Endpoint

Each project has its own MCP Cloud endpoint:

POST https://studio.example.com/api/mcp/v1/{projectId}/mcp

The /mcp suffix is the MCP Streamable HTTP transport mount point. The route is a catch-all, so the transport owns /mcp, its SSE stream, and session teardown under the same prefix.

Authentication

MCP Cloud uses Bearer API keys -- not session cookies:

Authorization: Bearer crn_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed crn_mcp_ and are roughly 50 characters. Only the SHA-256 hash is stored server-side; the plaintext key is shown exactly once at creation time and cannot be recovered afterward. Each key is scoped to a single project -- a key whose projectId does not match the route returns 403.

Creating a key

Keys are created in Workspace settings → MCP Cloud. Workspace owner or admin role is required. When you create a key you can set:

Option	Description
name	Display label for the key (required)
projectId	The project the key is scoped to (required)
allowedTools	Per-key tool allowlist (optional; empty = unrestricted)
rateLimitPerMinute	Per-minute request cap (optional; default 60, range 1–600)
monthlyCallLimit	Per-key monthly tools/call cap (optional; only ever tightens the plan cap, never exceeds it)

Connecting a client

The MCP Cloud panel surfaces ready-to-paste connection snippets after a key is created.

Claude Code (and any client supporting claude mcp add):

claude mcp add --transport http contentrain \
  https://studio.example.com/api/mcp/v1/{projectId}/mcp \
  --header "Authorization: Bearer crn_mcp_..."

JSON config (Claude Desktop, Cursor, and similar):

{
  "mcpServers": {
    "contentrain": {
      "type": "http",
      "url": "https://studio.example.com/api/mcp/v1/{projectId}/mcp",
      "headers": { "Authorization": "Bearer crn_mcp_..." }
    }
  }
}

Tool allowlist

Each key carries an allowed_tools list:

• Empty -- the key may call any tool in the remote surface (see below).
• Non-empty -- the key is restricted to exactly those tool names. A call to any other tool returns 403. Allowlists are validated against the call body before the monthly quota is touched, so a denied call never consumes quota.

Use a narrow allowlist for read-only or CI keys (for example, contentrain_content_list + contentrain_describe for a key that only audits content).

Rate limits and quota

Two independent limits apply.

Per-minute rate limit. Every request -- protocol traffic included -- is checked against a per-key sliding window (the key's rateLimitPerMinute, default 60). Exceeding it returns 429 with a Retry-After header (in seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Monthly call quota. Each plan grants a number of MCP calls per month, and a per-key monthlyCallLimit may tighten it further. The quota is incremented atomically; once exhausted, tools/call requests return 429.

Quota semantics

Only tools/call requests consume the monthly quota and produce usage/meter events. Protocol traffic -- initialize, tools/list, the SSE GET stream, and session DELETE -- is still rate-limited but is free. You pay for tool calls, not handshakes.

Remote tool surface

MCP Cloud runs against Studio's GitHub-backed provider, which has no local worktree. The merge and review lifecycle is owned by Studio, not the remote agent, so the remote surface is deliberately reduced.

Available over MCP Cloud:

Tool	Purpose
contentrain_status	Project status and stats
contentrain_describe	Inspect models and content shape
contentrain_describe_format	Directory format reference
contentrain_content_list	List entries
contentrain_content_save	Create or update content
contentrain_content_delete	Delete content
contentrain_model_save	Create or update a model
contentrain_model_delete	Delete a model
contentrain_validate	Validate content (without fix)

Not available over MCP Cloud -- these return a capability error:

contentrain_merge, contentrain_branch_list, contentrain_branch_delete, contentrain_submit, contentrain_init, contentrain_scaffold, contentrain_bulk, contentrain_doctor, contentrain_scan, contentrain_apply, and contentrain_validate with fix: true.

These are local-worktree or Studio-owned lifecycle operations. The merge/review flow happens in Studio, not in the remote client.

How remote writes land

The remote write path always reports pending-review: a write does not go straight to the content branch. Instead it lands as a cr/* branch, exactly like any other content change.

Studio then reconciles it according to the project's effective workflow:

• If the project resolves to auto-merge, the cr/* branch is landed automatically (fire-and-forget, after the agent has already received its response).
• If the project resolves to review (the workflow.review plan feature is available and config.workflow === "review"), the branch stays pending until a human approves it in Studio.

This keeps MCP Cloud writes consistent with Studio's native write paths and the dashboard's branches and review flow.

Plan gating

MCP Cloud is gated by the api.mcp_cloud feature plus the api.mcp_keys and api.mcp_calls_per_month limits.

Plan	MCP Cloud	API keys	Calls / month
Free	No	0	0
Community (self-host)	Yes	Unlimited	Unlimited
Starter	Yes	1	5,000
Pro	Yes	15	150,000
Enterprise	Yes	Unlimited	Unlimited

MCP Cloud is not an Enterprise-only feature: it is available on Starter and above, and unlimited on the AGPL Community self-host tier. Only the Free tier has it disabled.

MCP Cloud vs the Conversation API

Both are public, key-gated /v1/ surfaces, but they serve different needs:

	MCP Cloud	Conversation API
Protocol	Raw MCP tool access (the agent runs in your client)	Chat over REST (Studio's agent runs server-side)
Key prefix	crn_mcp_	crn_conv_
Edition	Available Starter+ and Community	Enterprise Edition only
Use case	Bring your own agent/IDE	Drive Studio's built-in agent programmatically

Next Steps

• API Reference -- the full HTTP surface and the public-vs-internal split
• Conversation API -- the EE-only chat alternative
• Contentrain Format -- the .contentrain/ structure MCP tools read and write
• Branches & Review -- where cr/* pending-review branches are approved
• Agent System -- how Studio's own agent uses the same tools