MCP server

The MCP server lets an assistant run your workspace in plain conversation: "how many credits do we have?", "make two episodes for Load Path, no more than 500 credits", "what is waiting for my approval?". It speaks the Model Context Protocol, so Claude, ChatGPT, Cursor, Claude Code, n8n and any other MCP client can use it without custom code.

https://forge.storeswiki.com/api/mcp

It is one endpoint, over Streamable HTTP, for workspaces on Pro and above.

What it does#

• It acts for one workspace, the one you connected — every tool reads and changes that workspace only, and an id from another workspace answers "not found", exactly like one that does not exist. whoami says which workspace it is, its plan, the credits available and what the connection may do.
• It carries ChannelForge's own data: projects, channels, episodes, jobs, credits, prices, approvals, schedules, films and the link of each post ChannelForge made. It never passes on a platform's views, likes, comments or analytics, nor an account's name as a platform gives it.
• It never posts. Approving an episode lets its channel's schedule post it in its next slot; the schedule itself is switched on by a person in the app. A connection can change a schedule's times or pause it, never switch one on.
• It spends only after a price. Generating episodes needs a ceiling at least the quoted price (below).
• Every change is recorded in the workspace's audit log, with the connection's name.

Connect it#

Claude and ChatGPT: sign in with ChannelForge#

These connectors sign in with OAuth: you never paste a key.

1. Add a custom connector with the address above. In Claude: Settings → Connectors → Add custom connector. In ChatGPT: Settings → Connectors (developer mode), then create a connector with the address. (These labels are Claude's and ChatGPT's own and may change.)
2. You are sent to ChannelForge's Connect an app page. Sign in if you are not already.
3. Choose the Workspace it acts for. Only workspaces where you are an owner or an admin, with a plan that has API access, can be chosen; the others are listed with the reason.
4. Under It may, keep the permissions you want it to have (below), then press Allow.
5. Ask it "what is my ChannelForge workspace?" — it calls whoami and answers.

The app is then listed in Settings → API & webhooks → Connected apps, with what it may do, who connected it and when it was last used. Revoke ends it at once. A connection also stops working by itself when the person who connected it is no longer an owner or admin of the workspace.

Claude Code#

Clients that send a header use a workspace API key; the key's scopes are the connection's scopes.

claude mcp add --transport http channelforge https://forge.storeswiki.com/api/mcp \
  --header "Authorization: Bearer fk_live_…"

Cursor#

In .cursor/mcp.json:

{
  "mcpServers": {
    "channelforge": {
      "url": "https://forge.storeswiki.com/api/mcp",
      "headers": { "Authorization": "Bearer fk_live_…" }
    }
  }
}

n8n#

Add an MCP Client Tool node to an n8n agent workflow: the endpoint above, Server Transport HTTP Streamable, and Bearer authentication with a workspace API key. Once it is published, the ChannelForge community node gives the same actions as ordinary n8n operations — see n8n, Make and Zapier.

Anything else#

Any client that speaks MCP over Streamable HTTP works: send JSON-RPC messages with POST, the header Authorization: Bearer fk_live_… (or an OAuth access token, below) and Content-Type: application/json.

The tools#

The film tools are listed where the workspace has long-form films, the storyboard tools where storyboard approval is on, and revise_episode where the editor is on; the list does not change while a client is connected. Each tool's own description tells the assistant how to use it, and its answers start with one plain sentence before the data.

A few details worth knowing when you ask for things:

• list_episodes filters by channel, state, kind (short, translation, compilation) and created_after, 20 at a time (up to 50), with a cursor for the next page.
• get_episode adds 15-minute links to the video and thumbnail when asked (include_media_links: true), for a ready or published episode.
• set_schedule takes 1 to 12 times of day as HH:MM and an IANA time zone such as Europe/Rome; pause: true switches the schedule off.
• generate_episodes needs the channel's kit to be built, and takes 1 to 5 episodes at a time.

Permissions#

On the consent screen the scopes are shown in words. A connection made with an API key has the key's scopes.

Every scope may read. When a connection lacks a tool's scope, a connector signed in with OAuth gets the standard 403 insufficient_scope answer naming the scope, so it can ask you to allow more; a connection with an API key gets a message naming the scope a new key needs.

Spending: a price first, then a ceiling#

An assistant cannot spend more than you were shown:

1. quote gives the credits each episode holds, the total for the count asked, what episodes like it typically cost, and whether the workspace has enough. Its max_credits_to_pass is the number to pass on.
2. generate_episodes needs max_credits. If what it would hold is more, it is refused with nothing queued or spent, and the message says the amount needed.
3. Each episode is charged what it really cost when it is ready, and the rest of its hold comes back. An episode the critic holds back, and a failure on ChannelForge's side, cost nothing.
4. idempotency_key makes a retried request return the same jobs instead of queuing more.

The workspace's and the channel's monthly spending caps apply to every job an assistant starts, as they do in the app; cancel_job stops one (a queued job releases its credits at once). See Billing, invoices and caps.

A conversation, for example#

Assistants usually ask before calling a tool that spends credits or changes something; the tools mark which do.

For client developers#

Transport and protocol#

• Streamable HTTP, stateless. The server speaks the current revision (2026-07-28, with server/discover) and the earlier, handshake-based ones that open with initialize (2025-11-25 down to 2024-11-05).
• Send JSON-RPC messages with POST and Content-Type: application/json, up to 64 KB each. Answers are JSON. The server keeps no sessions and opens no streams: GET and DELETE answer 405.
• No change notifications: the tools do not change while a client is connected.
• A request from a page of another website (an Origin header that is not ChannelForge's) is refused with 403.

Sign-in with OAuth 2.1#

ChannelForge runs its own authorisation server for the MCP endpoint, following the MCP authorisation specification.

• An unauthenticated request gets 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="read write jobs publish".
• Discovery documents (public, cacheable for five minutes):

https://forge.storeswiki.com/.well-known/oauth-protected-resource/api/mcp
https://forge.storeswiki.com/.well-known/oauth-authorization-server

• Clients: a Client ID Metadata Document (the client_id is an https address of a JSON document that names itself by that address and lists its redirect URIs), or Dynamic Client Registration at /api/oauth/register — 10 registrations an hour per address and 500 a day in all.
• Redirect URIs use https, or http to a loopback host for an app on a computer. They are matched exactly, but any port on a loopback address, as native apps need. A request with an address the client did not register is shown an error and never redirected.
• The flow: the authorisation code flow at /oauth/authorize, with PKCE using S256 only; the answer carries iss (RFC 9207). Without a scope, all four are asked.
• Audience: tokens are issued for the MCP endpoint alone — send resource=https://forge.storeswiki.com/api/mcp — and are accepted nowhere else (the REST API takes API keys only).
• Lifetimes: an authorisation code lasts five minutes and works once (presenting it again revokes every token it gave); an access token lasts an hour; a refresh token lasts 30 days and is replaced at every use (a spent one presented again ends the whole sign-in). A refresh may keep or narrow the scopes, never widen them.
• Token endpoint /api/oauth/token and revocation /api/oauth/revoke (RFC 7009): 60 requests a minute per address each. Revoking a refresh token ends its sign-in; revoking an access token ends that token.

Limits and refusals#

Troubleshooting#

• "MCP and API access are in the Pro plan and above." The workspace's plan has no API: see Pricing.
• The connector cannot find my workspace. Only owners and admins connect apps; the Workspace list on the consent screen says why any other workspace cannot be chosen.
• "This API key lacks the "jobs" scope …". Create a key with that scope in Settings → API & webhooks and use it instead; a key's scopes cannot be changed after it is made.
• "This would hold N credits … more than max_credits …". Ask for the quote again: the hold depends on the count and the quality, and max_credits must be at least the new total.
• "… has no kit yet". Build the channel's kit first, in the app or with the REST API.
• The film or storyboard tools are missing. They are listed only where those features are on for the workspace.

Related#

• Developer overview — keys, scopes, limits and the spending safeguards.
• REST API reference — the same workspace over plain HTTP; GET /quote, /episodes/generate, /episodes/{id}/approve and /reject are REST twins of the MCP tools.
• Approvals on your phone — the approval queue the assistant works with.
• Security — how connections and tokens are protected.