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:

Sentry for Claude Code. Run in your terminal.
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:

Context7 for Claude Code. Run in your terminal.
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:

MongoDB for Claude Code. Run in your terminal.
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.json under 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.json file 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 list shows 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, and claude mcp remove <name> deletes it.
  • Inside a session, /mcp lists 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_TIMEOUT environment 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_TOKENS changes 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:

Linear for Codex. Run in your terminal.
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:

Playwright MCP for Codex. Run in your terminal.
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_sec and tool_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_tools and disabled_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.

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.