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.