MCP reference

Connect your agent to Codexroom over MCP.

Codexroom runs a Model Context Protocol server at /api/mcp with OAuth 2.0 and PKCE. Below are the tools, the resources, the scopes, and the worked OAuth flow.

Authorise a test client

The transport

JSON-RPC over HTTP with Server-Sent Events.

JSON-RPC over HTTP with Server-Sent Events for server-initiated messages. The official @modelcontextprotocol/sdk Node package handles the protocol mechanics. Codexroom implements the rest.

The OAuth flow

Six steps from client launch to authenticated tool call.

The MCP client opens GET /api/mcp/oauth/authorize with client_id, scope, and code_challenge.
Codexroom routes the user through Clerk sign-in if needed, then the consent screen.
The user approves the scopes and the workspace.
Codexroom redirects back to the client with an authorisation code.
The client exchanges the code at POST /api/mcp/oauth/token for an access token (and a refresh token).
Subsequent MCP requests include the access token in the Authorization header.

Tokens scope to a single workspace, a single user, and a single client. Revoke any of them and the agent goes dark.

The scopes

Twelve scopes. Compose any subset.

A typical agent grant: tokens:read assets:read templates:read decks:write shares:write. The agent reads brand and composes decks. The brand stays locked.

Scope

What it grants

tokens:read

Read tokens, resolve them under a context.

tokens:write

Create + edit + publish tokens.

slot-types:read

Read slot-type definitions.

slot-types:write

Create + edit + publish slot types.

templates:read

Read slide + deck templates.

templates:write

Create + edit + publish templates.

assets:read

Search the data room.

assets:write

Create + update + archive assets.

decks:read

Read decks + their validation state.

decks:write

Create + update decks; run validate_deck.

shares:read

List shares + read their gate config.

shares:write

Create + revoke + rotate shares.

The tools

Typed tools mapped to the API surface.

Token tools

resolve_tokens(names, context?)

list_tokens(filter?)

Slot type and template tools

list_slide_templates(filter?)

list_deck_templates()

get_template(id)

Asset tools

search_assets(kind, context?, require?, limit?)

get_asset(id)

Deck tools

create_deck(name, deck_template_id, slide_instances)

validate_deck(deck_id)

update_deck_slot(deck_id, slide_index, slot_name, value)

get_deck(deck_id)

Share tools

create_share(deck_id, recipient_name?, scope?, password?, watermark_config?, gates?)

list_shares(deck_id)

revoke_share(share_id)

Each tool returns a typed result. Errors return the structured envelope from the foundation API surface.

The resources

Read-once context at the start of a conversation.

brand://current The workspace's full brand system (tokens, fonts, colours).

templates://slides The indexed list of slide templates.

data-room://summary Data room contents grouped by kind, with counts.

Read-once context an agent can load at the start of a conversation and reference throughout.

Worked example

From prompt to watermarked link in seven calls.

A sales lead in Claude Desktop says: "Pull together a pitch for Memorial Health, lead with the healthcare case study, password the share with the deal codename."

The agent's tool calls, in order

agent trace

// 1. list_deck_templates()
// → returns "sales-pitch-deck"

// 2. get_template("sales-pitch-deck")
// → returns the slot contract

// 3. search_assets("logo", { subject: "Memorial Health" })
// → returns the logo asset

// 4. search_assets("case_study", { industry: "healthcare" })
// → returns the case study

// 5. search_assets("metric", { label: "active enterprise customers" })
// → returns the metric

// 6. create_deck({ name, deck_template_id, slide_instances })
// → returns the validated deck

// 7. create_share({
//      deck_id,
//      recipient_name: "Memorial Health",
//      scope: "password",
//      password: "..."
//    })
// → returns the share URL

The agent returns the URL to the user. End to end, the workflow runs in under 30 seconds.

Tested clients

Five tested clients on day one.

Claude Desktop. Cursor. OpenAI Agents SDK. LangChain MCP adapter. Cline.

Known quirks land in the changelog as they appear.

See it work

Authorise a test client now.

Authorise a test client Book a developer call