How to connect Codex, Gemini, Copilot, Cursor and the Claude apps to ChessMotion
ChessMotion MCP is not only for Claude. Any assistant that can reach a remote MCP server and send your API key in a header can use it, and the big ones can: OpenAI’s Codex, Google’s Gemini CLI, GitHub Copilot and Cursor. This guide sets up each one, and says plainly which apps cannot connect yet and why.
The short version
Make a key in Settings → Agents & API keys, save it in an environment variable called CHESSMOTION_API_KEY, and add the server https://chessmotion.com/api/mcp to your client with the header Authorization: Bearer and the key. Codex reads it from config.toml, Gemini CLI takes one command, Copilot and Cursor read a JSON file. ChatGPT on the web and the Gemini app cannot connect yet.
Which assistants connect today
Every assistant below is an MCP client. What decides whether it can use ChessMotion is not the model behind it but two things the client has to do: reach a remote server over Streamable HTTP, and send a header with your key. These are the big ones, by their makers’ own documentation as of November 2026:
- Claude (Anthropic): Claude Code, with one command. The Claude apps, as a custom connector with a request header, where Anthropic’s request-header beta is open to your account.
- Codex (OpenAI): Codex in the terminal, in your editor or in the ChatGPT desktop app, which share one config.toml. Not yet: ChatGPT on the web signs in to MCP servers with OAuth only, so it cannot connect yet.
- Gemini CLI (Google): Gemini CLI, with one command. Not yet: The Gemini app’s custom apps have no documented way to send an API key, so it cannot connect yet.
- GitHub Copilot (GitHub): Copilot in VS Code, from an MCP configuration file with the key in a header.
- Cursor (Anysphere): Cursor, from its mcp.json with the key in a header.
MCP connects the client, not the model. In Cursor and GitHub Copilot you choose the model — OpenAI’s GPT, Anthropic’s Claude or Google’s Gemini among them — and ChessMotion’s tools are the same whichever you pick.
Before you start: a key, kept out of your files
Make a key in Settings → Agents & API keys, as in How to connect Claude to ChessMotion: give it a name for the client it is for, choose Read only or Create videos, and copy it. It starts with cmak_ and is shown only once.
Most clients below can read the key from an environment variable instead of the configuration file, which keeps it out of anything you might share or commit. The examples use one called CHESSMOTION_API_KEY. On macOS and Linux, add export CHESSMOTION_API_KEY="cmak_…" to your shell profile, such as ~/.zshrc. On Windows, run setx CHESSMOTION_API_KEY "cmak_…" and open a new terminal. Start the client from a terminal that has the variable.
ChessMotion MCP is included in Creator, Creator Live and Club Live, and the assistant works with everything those plans include: premium templates, Full HD and your Brand Kit. Free and Starter don’t include MCP or API keys.
Codex, in the terminal, your editor or the ChatGPT desktop app
OpenAI’s Codex keeps its MCP servers in config.toml, in the .codex folder of your home directory. The Codex CLI, the editor extension and the ChatGPT desktop app share that file, so one entry works in all three. Codex sends the bearer token itself: you give it the name of the environment variable, not the key.
- Set the variable: Make sure CHESSMOTION_API_KEY holds your key in the environment Codex starts from.
- Add the server: Open ~/.codex/config.toml and add the table below. The name in the brackets is what Codex calls the server.
- Restart and check: Start Codex again and ask “Who am I on ChessMotion?”. If the variable was missing when Codex started, it connects without the key and ChessMotion answers that the request is unauthenticated.
In ~/.codex/config.toml: [mcp_servers.chessmotion] url = "https://chessmotion.com/api/mcp" bearer_token_env_var = "CHESSMOTION_API_KEY"
Gemini CLI
Google’s Gemini CLI adds a remote server with one command. The -s user option saves it in the settings file in your home folder; without it, Gemini CLI writes to the project’s own settings, where a key is easier to share by mistake. In that file the server appears under mcpServers with httpUrl, the address for Streamable HTTP, and your header under headers.
Google’s documentation notes that for unpaid-tier and Google One users, Gemini CLI was replaced by Antigravity CLI in June 2026. These steps are for Gemini CLI.
Run the command with your key in place of cmak_…, then run gemini mcp list to see the server, and ask Gemini “Who am I on ChessMotion?”.
The command for Gemini CLI: gemini mcp add -s user --transport http --header "Authorization: Bearer cmak_…" chessmotion https://chessmotion.com/api/mcp
GitHub Copilot in VS Code
GitHub Copilot reads MCP servers from a JSON file: .mcp.json at the root of a workspace for one project, or mcp-config.json in the .copilot folder of your home directory for all of them. The entry below is an HTTP server whose Authorization header takes the key from CHESSMOTION_API_KEY, and the tools line makes all of ChessMotion’s tools available; you still choose what the key may do when you make it.
VS Code’s older .vscode/mcp.json format, which could prompt for the key, belongs to a mode VS Code has deprecated, so the file below is the one to use for new setups. Do not put the key itself in a workspace file you commit.
In .mcp.json or ~/.copilot/mcp-config.json: { "mcpServers": { "chessmotion": { "type": "http", "url": "https://chessmotion.com/api/mcp", "headers": { "Authorization": "Bearer ${CHESSMOTION_API_KEY}" }, "tools": [ "*" ] } } }
Cursor
Cursor reads mcp.json from the .cursor folder in your home directory for every project, or from .cursor in a project for that project only. A remote server needs the url and its headers, and Cursor fills in ${env:CHESSMOTION_API_KEY} from your environment. Cursor loads the file when it starts, so restart it after editing.
In ~/.cursor/mcp.json: { "mcpServers": { "chessmotion": { "url": "https://chessmotion.com/api/mcp", "headers": { "Authorization": "Bearer ${env:CHESSMOTION_API_KEY}" } } } }
The Claude apps
Claude Code connects with the one command in How to connect Claude to ChessMotion. The Claude apps on the web and the desktop can add ChessMotion MCP as a custom connector that sends a request header — a beta Anthropic is opening to accounts in turn. If you do not see Request headers when you add a custom connector, it is not open to your account yet.
- Add a custom connector: In Claude, open Customize, then Connectors, choose Add and Add custom connector. Name it ChessMotion and enter https://chessmotion.com/api/mcp as the server URL.
- Choose no sign-in, and add the header: Under Authentication choose No sign-in. Under Request headers choose authorization and enter Bearer, a space and your key. Claude sends the value exactly as you type it.
- Add it and check: Add the connector and ask Claude “Who am I on ChessMotion?”. Authentication settings cannot be changed later; to use a new key, remove the connector and add it again.
On Claude’s Team and Enterprise plans an owner adds connectors for the whole organisation, and everyone would act as the account that owns the key. Use a key of your own on a personal Claude account instead.
ChatGPT on the web and the Gemini app
ChatGPT on the web adds MCP servers through plugins, and OpenAI’s documentation says it cannot present custom API keys. ChessMotion signs in with an API key, so ChatGPT on the web cannot connect yet. Codex, including Codex in the ChatGPT desktop app, can, as above.
Custom apps in the Gemini app take an MCP server address, for adults in the US with a personal Google Account, but Google documents no way to send an API key with them, so the Gemini app cannot connect yet either. Gemini CLI can.
It signs in with an API key in an Authorization header. Clients that can only sign in with OAuth cannot connect yet. When either app can send a key, this guide will say so. In the meantime the tools are the same in every client that connects, so nothing you would ask for is missing.
Check that it works
Whichever client you use, ask “Who am I on ChessMotion?”. The assistant calls the identity tool and answers with the key’s name, your plan, your credit balance and the scopes the key has. Then ask for something small, such as your recent games, before you ask for a video. How to make chess videos with an AI assistant has requests that work well.
- Unauthenticated: the header is missing or the key is wrong. Check that the variable is set where the client starts, and that the header reads Bearer, a space and the whole key.
- The client asks you to sign in with a browser: it is trying OAuth, and a client that can only sign in with OAuth cannot connect, so check that the header is configured.
- A tool is refused for a missing scope: make a key with the permissions you need and revoke the old one.
- Refused for your plan: MCP and API keys are included in Creator, Creator Live and Club Live. ChessMotion MCP explains what each plan includes.
More about what the assistant can and cannot do: ChessMotion MCP.
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
Can I use ChessMotion in ChatGPT?
Not on the web yet. ChatGPT there signs in to MCP servers with OAuth only, so it cannot connect to ChessMotion, which uses an API key. OpenAI’s Codex can, in the terminal, your editor or the ChatGPT desktop app, with the key in its config.toml.
Does ChessMotion work with Gemini?
With Gemini CLI, yes: one command adds the server with your key in a header. The Gemini app documents no way to send an API key to a custom app, so it cannot connect yet.
Does it work with GitHub Copilot?
Yes. Add ChessMotion to Copilot’s MCP configuration as an HTTP server with your key in an Authorization header, read from an environment variable. This guide covers GitHub Copilot in VS Code, not Microsoft’s other Copilot apps.
Which model should I use?
Any model your client offers for tool use. ChessMotion does the chess, the analysis and the rendering; the model decides which tools to call and in what order. The tools and their results are the same whichever model calls them.
Why keep the key in an environment variable?
So it is not written in a configuration file you might share, sync or commit. Anyone with the key can act on your account within its scopes. If it leaks, revoke it in Settings and make a new one.
Can several assistants share one key?
They can, but a key per assistant is easier to manage: revoking one leaves the others working, and the key list shows when each was last used. Up to 10 keys can be active at a time.
Which ChessMotion plans include MCP?
Creator, Creator Live and Club Live. Free and Starter don’t include MCP or API keys. Renders use your plan’s credits at the editor’s prices, whichever assistant asks for them.
Sources
- OpenAI: Model Context Protocol (Codex) — config.toml, bearer_token_env_var, and what ChatGPT on the web reads.
- OpenAI: Plugin authentication — why ChatGPT on the web cannot present an API key.
- Gemini CLI: MCP servers — httpUrl, headers and gemini mcp add.
- Gemini Apps Help: Connect and manage custom apps — custom apps in the Gemini app, and who can use them.
- VS Code: MCP configuration reference — HTTP servers and headers for GitHub Copilot.
- Cursor Docs: Model Context Protocol — remote servers, headers and environment variables.
- Claude: Add a connector that isn’t in the directory — custom connectors in the Claude apps, and request-header authentication (beta).
Read next: ChessMotion MCP, How to connect Claude to ChessMotion, How to make chess videos with an AI assistant and ChessMotion Agent.