Connect Claude, ChatGPT and Codex to Contentrain Studio

Studio exposes a single OAuth-authenticated MCP endpoint that AI apps connect to. Unlike the API-key surface (MCP Cloud, /api/mcp/v1/{projectId}), the remote endpoint is the same URL for everyone -- which project it operates on is decided during sign-in, not by the URL.

https://studio.contentrain.io/api/mcp/remote

Self-hosting? Replace studio.contentrain.io with your own host.

The client only needs this URL. There is no key to paste and no MCP server to run: the app discovers Studio's OAuth server, opens a browser for sign-in and consent, and receives its own tokens.

Connector vs. MCP Cloud

Both surfaces speak the same MCP tools against the same content, but they authenticate differently. The connector (this page) uses interactive OAuth -- the user signs in and picks a project in the browser, ideal for directory-listed apps like Claude and ChatGPT. MCP Cloud uses long-lived crn_mcp_ Bearer keys scoped to one project -- ideal for CI and headless automation.

Before you start

The remote connector requires:

The managed provider pair -- NUXT_AUTH_PROVIDER=managed + NUXT_DATABASE_PROVIDER=postgres. Studio itself acts as the OAuth authorization server; the Supabase pair delegates auth to GoTrue and therefore cannot host it. See Self-Hosting and Environment Variables.
A connected project with content -- the connection is bound to a workspace and project chosen at sign-in.
A plan that includes api.mcp_cloud_oauth -- Community, Starter, Pro, and Enterprise. The Free tier does not have it.

How connecting works

The flow is standard OAuth discovery → consent → token:

You add the endpoint URL to your AI app (steps below). The app discovers Studio's OAuth server automatically (RFC 9728 protected-resource metadata / RFC 8414 authorization-server metadata).
Your browser opens Studio. You sign in (if needed) and land on the consent screen.
You pick the workspace and project this connection may access and approve the requested permissions.
The app receives its tokens and starts calling MCP tools. Access tokens expire after 1 hour; apps refresh silently for up to 30 days (the offline_access scope).

One connection = one project

The project is fixed at consent time. To operate on a different project, connect again and pick another one -- the old connection stays active until you disconnect it.

Connecting each client

Claude (claude.ai / Desktop) -- Settings → Connectors → Add custom connector → paste the endpoint URL. Claude shows a Connect card; approve in the browser popup.

Claude Code -- and any client supporting claude mcp add:

bash

claude mcp add --transport http contentrain \
  https://studio.contentrain.io/api/mcp/remote

The OAuth window opens on first use; the callback returns to an ephemeral localhost port automatically (RFC 8252 loopback redirect).

ChatGPT (developer mode) -- Settings → Security and login → enable Developer mode, then add the endpoint as an MCP server under Settings → Plugins.

Codex:

toml

# ~/.codex/config.toml
[mcp_servers.contentrain]
url = "https://studio.contentrain.io/api/mcp/remote"

Then run codex mcp login contentrain.

MCP Inspector (debugging) -- point it at the endpoint URL; it walks the same discovery + consent flow and lets you exercise every tool.

Permissions (scopes)

At consent you approve a set of scopes. Each scope unlocks a group of MCP tools:

Scope	Grants	Tools
`project:metadata`	Project structure reads	`contentrain_status`, `contentrain_describe`, `contentrain_describe_format`
`content:read`	Content reads	`contentrain_content_list`
`content:write`	Content and model writes	`contentrain_content_save`, `contentrain_content_delete`, `contentrain_model_save`, `contentrain_model_delete`, `contentrain_validate`
`media:read`	Media reads	`contentrain_media_list`, `contentrain_media_get`
`media:write`	Media writes	`contentrain_media_ingest` (from a URL), `contentrain_media_update`, `contentrain_media_delete`
`offline_access`	A refresh token -- stay connected without re-approving	—

Media scopes are conditional

The media:* scopes are advertised only on deployments where the media stack is configured (Enterprise + object storage). The media tools additionally require the workspace plan's media.upload feature and the project's CDN delivery being enabled -- where any of those is missing, the tools do not appear at all. Ingest is URL-only (MCP has no binary channel); the fetch is SSRF-guarded, MIME-whitelisted, and size-capped server-side.

Remote connections and API keys draw on the same api.mcp_calls_per_month workspace quota.

What the connector can and cannot do

Can:

Read project structure, content, and models.
Write content and models -- with content:write approved.
Read and write media -- where the media stack, plan feature, and CDN are all enabled.

Cannot -- these tools are never exposed over the remote endpoint:

The merge/review lifecycle tools -- there is no merge tool, no branch listing/deletion, no submit/apply.

Content writes always land as cr/* branches and follow the project's effective workflow -- auto-merged, or held for a human to approve -- exactly like the API-key surface. Media writes go through the media service, not git. The merge/review flow happens in Studio, not in the connected client. See Branches & Review and Roles & Permissions.

Managing connections

Workspace Settings → Connected Apps lists every active connection with its client, project, scopes, and monthly call count.

Workspace owners/admins see and can disconnect every connection in the workspace; members see and manage only their own.
Disconnect revokes the connection's refresh-token family and deletes its live access tokens immediately -- the app's next request fails with a clean re-authorization prompt; nothing breaks silently.
Deleting the project or removing the user cascades the connection away.

Troubleshooting

Symptom	Cause & fix
The app can't reach the server	The endpoint requires HTTPS in production and the managed provider pair (see Before you start).
"Plan required" errors	The workspace plan doesn't include `api.mcp_cloud_oauth` -- upgrade in Settings → Billing.
`insufficient_scope` / permission errors	The connection's scopes don't cover the tool. Clients that support step-up authorization re-prompt for consent automatically; otherwise disconnect and reconnect with the missing scope (e.g. write access) approved.
`429` responses	The per-connection rate limit (60 requests/min) or the workspace's monthly MCP call quota. Usage is visible in Settings → Usage and on each Connected Apps row.

Next Steps

MCP Cloud -- the API-key surface for CI and headless automation
Branches & Review -- where cr/* pending-review branches are approved
Roles & Permissions -- who can connect and disconnect apps
Contentrain Format -- the .contentrain/ structure the MCP tools read and write
Agent System -- how Studio's own agent uses the same tools

Connect Claude, ChatGPT and Codex to Contentrain Studio ​

Before you start ​

How connecting works ​

Connecting each client ​

Permissions (scopes) ​

What the connector can and cannot do ​

Managing connections ​

Troubleshooting ​

Next Steps ​