How to connect Claude to ChessMotion
Connecting an AI assistant to ChessMotion takes a few minutes: a key from your settings, one entry in your MCP client, and a first question to check it works. This guide does it in Claude Code, then shows what other clients need.
The short version
Make a key in Settings → Agents & API keys with the Create videos preset and copy it. In Claude Code run the claude mcp add command below with your key. Then ask the assistant who it is on ChessMotion: the answer names the key, your plan, your credits and its permissions.
What you need
- A ChessMotion account on Creator, Creator Live or Club Live. Free and Starter don’t include MCP or API keys. On those plans Settings → Agents & API keys shows the upgrade instead of the key controls.
- An MCP client that can connect to a remote server over Streamable HTTP and send an Authorization header. Claude Code can; the steps below use it.
- Optionally, your Chess.com and Lichess usernames saved in your ChessMotion settings, so the assistant can find your recent games without links.
Step by step
- Open Agents & API keys: Sign in to ChessMotion and open Settings → Agents & API keys. Choose New API key and give it a name you will recognise later, such as the client it is for.
- Choose what it may do: Read only lets the assistant look at your games, projects, templates, renders and replays without changing anything. Create videos adds importing, creating and setting up projects, rendering and sharing replays. You can tick scopes one by one instead; analysis with Stockfish is a scope of its own that neither preset includes.
- Copy the key: Create the key and copy it straight away. It starts with cmak_ and is shown only this once: ChessMotion keeps a hash, not the key. If you lose it, revoke it and make another.
- Add the server to Claude Code: Run the command below in a terminal, with your key in place of cmak_…. It adds a remote HTTP server called chessmotion at https://chessmotion.com/api/mcp that sends your key with every request.
- Check the connection: Start Claude Code and ask “Who am I on ChessMotion?”. The assistant calls the identity tool and tells you the key’s name, your plan, your credit balance and the scopes it has. Ask “Which tools do you have from ChessMotion?” to see the list.
- Make something: Ask for a video. How to make chess videos with an AI assistant has requests that work well and what happens behind them.
The command for Claude Code: claude mcp add --transport http chessmotion https://chessmotion.com/api/mcp --header "Authorization: Bearer cmak_…"
Other MCP clients
Any client that supports remote MCP servers over Streamable HTTP with custom headers can connect. It needs two things: the address https://chessmotion.com/api/mcp and the header Authorization: Bearer followed by your key. Where your client takes a JSON configuration, the entry has a type of http, the url, and the header under headers; Claude Code’s own project file, .mcp.json, uses exactly that shape.
It signs in with an API key in an Authorization header. Clients that can only sign in with OAuth cannot connect yet. Agent frameworks and MCP client libraries work the same way: point their Streamable HTTP client at the address and pass the header.
Using Codex, Gemini CLI, GitHub Copilot, Cursor or the Claude apps? How to connect Codex, Gemini, Copilot and Cursor to ChessMotion has the exact setup for each.
The same server as JSON: { "mcpServers": { "chessmotion": { "type": "http", "url": "https://chessmotion.com/api/mcp", "headers": { "Authorization": "Bearer cmak_…" } } } }
Keeping the key safe
The key is a password for your ChessMotion account, limited to the scopes you chose. Anyone who has it can import games, create projects and — if it may render — spend your credits.
- Give each client or script its own key, so you can revoke one without touching the others.
- Give render permission only to keys you intend to render with; a read-only key is enough to browse.
- Do not paste the key into a chat, a screenshot or a file you commit to a shared repository.
- If a key leaks, revoke it in Settings → Agents & API keys. It stops working on its next call.
If something goes wrong
- The assistant says it is unauthenticated: the key is missing, mistyped or revoked. Check the header is exactly “Authorization: Bearer ” followed by the whole key.
- A tool is refused because a scope is missing: the key was made without that permission. Make a new key with the scopes you need and revoke the old one.
- A render is refused for credits: your balance does not cover it, and nothing was charged. Ask for a quote to see the price, or add credits.
- Too many requests: each key has per-minute limits, such as five renders a minute. Wait the number of seconds the answer gives and ask again.
- The client cannot add the server at all: it may support only local servers, or only sign-in with OAuth. Use a client that supports remote servers with headers, such as Claude Code, Codex, Gemini CLI, GitHub Copilot or Cursor.
Rather have ChessMotion pick the moments?
ChessMotion Agent needs no assistant and no instructions. It reads your games, finds 3 moments worth posting, makes the 9:16 videos and drafts the posts, and you approve, edit or reject each one. Free accounts can try it once. See ChessMotion Agent.
Frequently asked questions
Where do I find my ChessMotion API key?
In Settings, under Agents & API keys. A key is shown only when you create it, so if you did not copy it then, revoke it and create a new one.
Which scopes should I choose?
Read only to let an assistant browse your games and projects. Create videos to let it import, set up, render and share. Add analysis on its own if you want it to use Stockfish to pick moments.
Can I use the same key in several clients?
You can, but a key per client is easier to manage: revoking one then leaves the others working. Up to 10 keys can be active at a time.
Does connecting cost credits?
No. Only renders use credits, at the editor’s price. Checking who the key is, listing tools and importing games are free.
Why can’t I create a key?
MCP and API keys are included in Creator, Creator Live and Club Live. On Free or Starter, Settings shows them locked with an upgrade, and once you upgrade you can create a key straight away. A key stops working if the account moves to a plan without MCP, and works again after an upgrade.
Sources
- Claude Code Docs: Connect Claude Code to tools via MCP — adding a remote HTTP server with a header.
- MCP specification: Transports — Streamable HTTP, the transport ChessMotion’s server uses.
Read next: ChessMotion MCP, What the ChessMotion MCP server is, Connect Codex, Gemini, Copilot and Cursor and How to make chess videos with an AI assistant.