Two terminal agents, two registration commands, and one difference that decides how each of them authenticates.
Terminal agents are the easiest MCP clients to set up and the easiest to get subtly wrong, because the command that registers a server looks similar everywhere and the authentication does not.
Codex and Gemini CLI are a good pair to look at together: nearly identical commands, and both default to opening a browser rather than asking for a key. The difference is what happens if that browser flow does not fire for you — one of them has nothing else to fall back to, and the other does.
Codex
codex mcp add spinrun --url https://spinrun.ai/mcpNo headers. That is not an omission — codex mcp add does not accept them, and
this is the one case where that turns out to be an advantage.
Codex can complete a browser authorisation. Its first request reaches the gateway
without a credential, gets a 401 carrying a WWW-Authenticate header, follows
it, and runs the OAuth flow. A browser opens once, you pick a workspace, and the
terminal picks up from there.
Gemini CLI
gemini mcp add --transport http spinrun https://spinrun.ai/mcp \
--header "x-spinrun-client: gemini-cli"--transport http is required. Gemini CLI defaults to stdio, which expects a
local process; the gateway is remote HTTP. Without the flag the server registers
and then never connects, which looks like nothing happening rather than like an
error.
x-spinrun-client carries no secret and exists so the activity log can
attribute a call to Gemini CLI rather than leaving you guessing.
Gemini CLI's first request reaches the gateway with no credential attached and
gets a 401 back, carrying a WWW-Authenticate header that points at where to
authorize. It follows that header, opens a browser once, and you pick a
workspace — the same prompt Codex gets, just with one more header in the
command.
Let the agent register itself
Both of these are terminal agents, which means there is a shorter path than copying shell commands: tell the agent to do it.
Add the Spinrun MCP server at https://spinrun.ai/mcp and complete the browser
authorization it prompts for, then list the tools you can now reach.Ending with "list the tools you can now reach" is the useful part. A list of tools is proof that the registration worked; a success message is not.
What happens if the browser does not open
Every client the gateway talks to gets the same 401 and the same
WWW-Authenticate header — the browser flow is not special-cased per client,
so nothing here is a promise one of them keeps and another does not. What
differs is what is left to try if it does not fire for you.
| Client | Registration | If the browser does not open |
|---|---|---|
| Codex | codex mcp add | Nothing — the CLI has no flag for a header at all |
| Claude, ChatGPT | Remote MCP URL | Nothing — neither client takes a custom header |
| Gemini CLI, Claude Code | CLI command | A key, from your dashboard |
| Cursor, VS Code, Windsurf | Config file | A key, from your dashboard |
For the two rows with no fallback, that absence is not a bug to route around — it is the reason a leaked Codex or ChatGPT config cannot leak a credential, because there was never one in it to begin with.
Set the rules first
A terminal agent has a shell and now has your accounts too. Before that combination exists, set each connected app's policy: read, write and destructive, each allowed or blocked, enforced at the gateway rather than requested in a prompt.