Add MCP servers to Claude Code and Codex CLI
Both terminal agents register MCP servers with a single command. This guide covers the syntax for remote and local servers, where each tool stores the result, how OAuth sign-in works, and how to check that a server actually connected.
Before you start
Decide first whether the server you want is remote or local. A remote server has a URL such as https://mcp.notion.com/mcp; your client connects to it over HTTP. A local server is a command such as npx @playwright/mcp@latest that the client starts on your machine and talks to over standard input and output (stdio). Every listing in the registry states its transport, and remote vs local servers explains the trade-offs.
Local servers need whatever runtime their command uses. Most use npx, which comes with Node.js; some Python servers use uvx, which comes with uv; a few use Docker. Install those first, and run the command once in a terminal if a server fails to start: the error is usually clearer there than inside the agent.
Claude Code: add a remote server
Remote servers take the --transport http flag, a name of your choice and the URL. Claude Code's documentation uses Notion as its own example, and the registry's examples follow the same form:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Most vendor-hosted servers use OAuth. Adding the server only registers it; you sign in from inside Claude Code by running /mcp, selecting the server and following the browser prompt. Claude Code stores the token, refreshes it, and deletes the stored token and client registration if you later remove the server. Servers that need no account at all, such as documentation search, work as soon as they are added:
claude mcp add --transport http context7 https://mcp.context7.com/mcp
If a provider gives you an API key instead of OAuth, pass it as a header with --header "Authorization: Bearer ...". Claude Code also accepts the older SSE transport with --transport sse, but the MCP specification has replaced HTTP+SSE with Streamable HTTP, so prefer an /mcp endpoint when a provider offers both.
Claude Code: add a local server
For a local server, everything after a double dash (--) is the command Claude Code runs. Options for Claude Code itself, such as --env and --scope, go before the double dash; everything after it is passed to the server untouched. The registry puts them after the server name, as one of Claude Code's own examples does. If you put --env first, place another option such as --transport stdio between it and the name, because --env accepts several pairs and would read the name as one more. Variables set with --env are passed to the server process:
claude mcp add mongodb --env MDB_MCP_CONNECTION_STRING="$MDB_MCP_CONNECTION_STRING" -- npx -y mongodb-mcp-server@latest --readOnly
The "$MDB_MCP_CONNECTION_STRING" in the example is expanded by your shell when you run the command, so export the variable first. The value is then stored in Claude Code's configuration file. If you would rather not keep a credential in a file at all, prefer a server that supports OAuth.
Claude Code: choose a scope
Where a server is saved decides who can use it:
- Local scope is the default. The server is available only in the current project and only to you, and it is stored in
~/.claude.jsonunder that project's path. - User scope (
--scope user) makes the server available in all your projects, still privately in~/.claude.json. - Project scope (
--scope project) writes the server to a.mcp.jsonfile in the repository, so everyone who clones it gets the same configuration. Claude Code asks each person to approve project servers before it starts them.
A shared .mcp.json should never contain secrets. Claude Code expands ${VAR} and ${VAR:-default} references in that file, so teams can commit the shape of a configuration and keep tokens in each person's environment.
Claude Code: check and manage servers
claude mcp listshows every configured server with a status such as connected, needs authentication or failed to connect.claude mcp get <name>shows the details of one server, andclaude mcp remove <name>deletes it.- Inside a session,
/mcplists servers, starts OAuth sign-in and lets you disable a server for the current project without removing it. - Slow servers can be given more time to start with the
MCP_TIMEOUTenvironment variable, in milliseconds. Claude Code warns when a tool returns more than 10,000 tokens and caps output at 25,000 by default;MAX_MCP_OUTPUT_TOKENSchanges the cap.
If you have setup instructions written for another client, such as an mcpServers JSON block for Claude Desktop, claude mcp add-json <name> '<json>' accepts the inner server entry directly.
Codex CLI: add servers
Codex uses the same idea with slightly different flags. A remote server takes --url; for an OAuth server you then run codex mcp login with the same name, which opens the browser sign-in. The registry's Codex examples include that second line whenever a server uses OAuth:
codex mcp add linear-official --url https://mcp.linear.app/mcp
codex mcp login linear-official
Local servers use --env options and a double dash before the command, exactly as in Claude Code:
codex mcp add playwright-mcp -- npx @playwright/mcp@latest
codex mcp list shows what is configured. Codex stores servers in ~/.codex/config.toml, a file shared by the Codex CLI, the IDE extension and the ChatGPT desktop app, so a server added once is available in all three. A project can have its own .codex/config.toml, which Codex only reads for trusted projects.
Codex CLI: edit config.toml directly
Each server is a [mcp_servers.<name>] table. Local servers use command, args and env; remote servers use url. Useful optional keys include:
bearer_token_env_var: the name of an environment variable holding a bearer token, so the token itself never appears in the file.env_http_headers: headers whose values are read from environment variables.startup_timeout_secandtool_timeout_sec: how long Codex waits for the server to start (10 seconds by default) and for each tool call (60 seconds by default).enabled_toolsanddisabled_tools: an allow list and a deny list that limit which of a server's tools the agent can call.
[mcp_servers.linear-official]
url = "https://mcp.linear.app/mcp"
# Optional: only expose read tools to the agent
enabled_tools = ["list_issues", "get_issue", "list_projects"]
Tool names in enabled_tools must match what the server reports at runtime. The registry lists upstream examples; check the live list with your client before relying on an allow list.
Next steps
Pick a server from the registry: every listing has a Claude Code and a Codex example you can copy. Before connecting a server to a production account, read authentication and security basics.
More setup guides
Sources
This guide was written from the official documentation below and last reviewed on 12 October 2026. Client interfaces change often; when a menu or file name here differs from what you see, the upstream documentation wins. Report a correction through the contact page.