--- title: "How to add a remote MCP server to Claude Code, Codex, Cursor and Gemini CLI · Cork" description: "Exact, verified commands and config to add a remote HTTP MCP server to Claude Code, Codex, Cursor and Gemini CLI, with scopes, auth headers and OAuth sign-in." canonical: "https://corkcli.com/blog/add-remote-mcp-server-claude-code-codex-cursor-gemini-cli" last_updated: "2026-10-03" published: "2026-10-03" author: "Kevin Vera" --- # How to add a remote MCP server to Claude Code, Codex, Cursor and Gemini CLI Exact, verified commands and config to add a remote HTTP MCP server to Claude Code, Codex, Cursor and Gemini CLI, with scopes, auth headers and OAuth sign-in. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 5 min read To add a remote MCP server: in Claude Code run `claude mcp add --transport http `; in Codex run `codex mcp add --url `; in Cursor add `{"mcpServers": {"": {"url": ""}}}` to `.cursor/mcp.json` or `~/.cursor/mcp.json`; in Gemini CLI run `gemini mcp add --transport http ` (or set `httpUrl` in `settings.json`). For OAuth servers, sign in with `/mcp` in Claude Code, `codex mcp login ` in Codex, or `/mcp auth` in Gemini CLI. Every command below was checked against each tool's official docs as of October 2026. The examples use a placeholder server named `myserver` at `https://mcp.example.com/mcp`. Replace both with your own. ## Quick reference | Tool | Add command or file | Project-shared config | Auth | |---|---|---|---| | Claude Code | `claude mcp add --transport http myserver https://mcp.example.com/mcp` | `.mcp.json` (`--scope project`) | `/mcp` or `claude mcp login myserver`; `--header` for tokens | | Codex | `codex mcp add myserver --url https://mcp.example.com/mcp` | `.codex/config.toml` | `codex mcp login myserver`; `bearer_token_env_var` | | Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` | `.cursor/mcp.json` | `headers`; OAuth via `auth` block | | Gemini CLI | `gemini mcp add --transport http myserver https://mcp.example.com/mcp` | `.gemini/settings.json` (default scope) | `/mcp auth`; `--header` | ## Claude Code Add a remote HTTP server: ```bash claude mcp add --transport http myserver https://mcp.example.com/mcp ``` Pick a scope with `--scope` (or `-s`): - `local` (default): this project only, just you, stored in `~/.claude.json`. - `project`: this project, shared with the team through `.mcp.json` at the repo root. - `user`: all your projects, stored in `~/.claude.json`. ```bash claude mcp add --transport http --scope project myserver https://mcp.example.com/mcp ``` That writes: ```json { "mcpServers": { "myserver": { "type": "http", "url": "https://mcp.example.com/mcp" } } } ``` For a bearer token, add a header: `--header "Authorization: Bearer $TOKEN"`. In `.mcp.json`, use `"headers": {"Authorization": "Bearer ${API_KEY}"}`, since environment variables are expanded. For OAuth servers, run `/mcp` inside Claude Code and follow the browser sign-in, or run `claude mcp login myserver`. The `--transport sse` option still exists but the docs mark SSE as deprecated. Manage servers with `claude mcp list`, `claude mcp get myserver` and `claude mcp remove myserver`. ## Codex Add a remote server from the CLI: ```bash codex mcp add myserver --url https://mcp.example.com/mcp codex mcp login myserver # only for OAuth servers ``` Or edit `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`): ```toml [mcp_servers.myserver] url = "https://mcp.example.com/mcp" bearer_token_env_var = "MYSERVER_TOKEN" ``` Other options for HTTP servers include `http_headers` for static headers, `auth` set to `"oauth"`, and `enabled = false` to switch a server off without deleting it. For a pre-registered OAuth client, add `--oauth-client-id ` to `codex mcp add`, or a `[mcp_servers.myserver.oauth]` table with `client_id`. In the Codex TUI, `/mcp` lists the configured MCP tools. ## Cursor Cursor reads MCP servers from a JSON file: - Project: `.cursor/mcp.json` in the project root. - Global: `~/.cursor/mcp.json` in your home directory. ```json { "mcpServers": { "myserver": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` For OAuth servers that need static client credentials, Cursor's docs show an `auth` object with `CLIENT_ID`, `CLIENT_SECRET` and `scopes`; the documented redirect URLs are `https://www.cursor.com/agents/mcp/oauth/callback` (web) and `http://localhost:8787/callback` (desktop). Once the server connects, its tools appear under Available Tools, and you can enable or disable servers from the Customize sidebar panel. ## Gemini CLI Add a remote server with Streamable HTTP: ```bash gemini mcp add --transport http myserver https://mcp.example.com/mcp gemini mcp add --transport http --header "Authorization: Bearer abc123" myserver https://mcp.example.com/mcp ``` The scope flag `-s, --scope` takes `user` or `project`, and the default is `project`. Project config goes to `.gemini/settings.json`, user config to `~/.gemini/settings.json`. The equivalent settings entry: ```json { "mcpServers": { "myserver": { "httpUrl": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer your-api-token" } } } } ``` Note the field name: in Gemini CLI, `httpUrl` means Streamable HTTP, while `url` means an SSE endpoint. Manage OAuth with `/mcp auth` inside a session. ## Common problems - **Wrong transport.** Most modern remote servers speak Streamable HTTP. Use `--transport http` (Claude Code, Gemini CLI) or `httpUrl` (Gemini settings). In Gemini CLI, putting a Streamable HTTP endpoint under `url` treats it as SSE. - **Secrets in committed files.** Project-shared configs (`.mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json`, `.codex/config.toml`) are meant to be committed. Use environment variables (`${API_KEY}` in Claude Code, `bearer_token_env_var` in Codex) or OAuth instead of pasting tokens. - **Server added but not visible.** Check with `/mcp` (Claude Code, Codex) or the Customize panel (Cursor). In Claude Code, `/mcp reconnect all` retries failed servers. ## How Cork helps If the server you are adding is meant to coordinate several agents, every agent needs the same one. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. Cork's MCP server works with any MCP client, using the commands above: ```bash claude mcp add --transport http cork https://mcp.corkcli.com codex mcp add cork --url https://mcp.corkcli.com gemini mcp add --transport http cork https://mcp.corkcli.com ``` It exposes `get_symbol`, `blast_radius`, `recap`, and `remember` and `recall`. In Claude Code, Codex and Cursor, Cork's hooks also deliver briefings, live awareness of teammates' changes, a write gate and [semantic lint](https://corkcli.com/blog/semantic-lint) with no extra model calls. One command installs them for every repo on the machine: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### What is the command to add an HTTP MCP server to Claude Code? `claude mcp add --transport http `. Add `--scope project` to share it through `.mcp.json`, or `--scope user` for all your projects. ### Where is the MCP config file for Codex? `~/.codex/config.toml`, or `.codex/config.toml` in a project, with one `[mcp_servers.]` table per server. ### Where does Cursor store MCP servers? In `.cursor/mcp.json` in the project root, or `~/.cursor/mcp.json` for all projects. ### What is the difference between url and httpUrl in Gemini CLI? `httpUrl` uses Streamable HTTP. `url` is for SSE endpoints. ## Sources - - - - - ## Related reading - [MCP servers for coordinating coding agents: what they are and how to use one](https://corkcli.com/blog/mcp-servers-coordinating-coding-agents): What an MCP server for coordinating coding agents does, how it differs from hooks, and how to connect one to Claude Code, Codex, Cursor and Gemini CLI. - [How to run Codex and Claude Code side by side on one project](https://corkcli.com/blog/run-codex-and-claude-code-side-by-side): Run OpenAI Codex CLI and Claude Code on one repo: one AGENTS.md for both, a worktree each, shared MCP servers, matching hooks, and live coordination. - [Cork Free: set up multiplayer coding agents on one machine in one command](https://corkcli.com/blog/cork-free-setup-one-machine): Set up Cork Free in one command so Claude Code, Codex and Cursor agents on one machine stop overwriting each other. No account; data stays on the machine. - [Git worktrees for parallel AI coding agents: setup and limits](https://corkcli.com/blog/git-worktrees-parallel-ai-coding-agents): Set up git worktrees for parallel AI coding agents like Claude Code and Codex: exact commands, environment setup, cleanup, and what worktrees do not solve. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/add-remote-mcp-server-claude-code-codex-cursor-gemini-cli