# How to add an MCP server to Codex CLI > Add an MCP server to Codex CLI with codex mcp add and the server's command, or write its table in config.toml. OAuth servers sign in with codex mcp login. Source: https://shuriken.sh/guides/codex-cli-mcp-servers Add an MCP server to Codex CLI with codex mcp add and the server's command, or write its table in config.toml. OAuth servers sign in with codex mcp login. By Shuriken Updated 27 October 2026 4 min read **Contents** To add an MCP server to Codex CLI, run codex mcp add -- , for example codex mcp add context7 -- npx -y @upstash/context7-mcp. Codex saves it as a [mcp_servers.] table in ~/.codex/config.toml, and you can write those tables by hand too. A remote server takes a url, and one with OAuth signs in with codex mcp login . We took the commands and keys below from OpenAI's [MCP page for Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), first read on 23 October 2026 and checked again on 25 October 2026. codex mcp --help lists every subcommand your installed version has. ## Add a local server with codex mcp add # A local (stdio) server is a program Codex starts on your computer. Everything after -- is the command that starts it. OpenAI's full form, with environment variables passed through --env: bash codex mcp add --env VAR1=VALUE1 --env VAR2=VALUE2 -- Context7, a free server for developer documentation, is OpenAI's own example: bash codex mcp add context7 -- npx -y @upstash/context7-mcp codex mcp list prints what is configured. Inside a Codex session, /mcp shows the servers that are running. ## Add a remote server # A remote server speaks Streamable HTTP at an address. If its authorization server wants a pre-registered OAuth client, give the client ID when you add it: bash codex mcp add example --url https://mcp.example.com --oauth-client-id my-client For a confidential client, add --oauth-client-secret "$MCP_CLIENT_SECRET", read from an environment variable. Codex stores that secret in config.toml as mcp_servers.example.oauth.client_secret, so keep the file out of git. It also prints the callback to register with your provider, http://127.0.0.1/callback by default; register exactly the one it shows. Then sign in once: bash codex mcp login example --scopes read,write asks for specific scopes on that login, and a scopes key in the server's table sets them for good. With neither, Codex uses the scopes the server advertises. ## The same thing in config.toml # codex mcp add writes a table you can edit yourself. One per server: toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] [mcp_servers.example] url = "https://mcp.example.com" bearer_token_env_var = "EXAMPLE_TOKEN" The keys OpenAI documents: | Kind | Keys | | --- | --- | | Local (stdio) | command (required), args , env , env_vars , cwd | | Remote (HTTP) | url (required), bearer_token_env_var , http_headers , env_http_headers | | Either | enabled , required , startup_timeout_sec (default 10), tool_timeout_sec (default 60), enabled_tools , disabled_tools | bearer_token_env_var holds the name of an environment variable, not the token, so the token never lands in a file you might commit. env_http_headers does the same for other headers. enabled = false turns a server off without deleting it, and required = true makes Codex fail at startup if that server can't initialise. A project can carry its own servers in .codex/config.toml, which Codex reads only when you trust the project. Which file wins when both define a key is in our [config.toml guide](https://shuriken.sh/guides/codex-cli-config-toml). Shuriken keeps one MCP list for all your agents, and an MCP sign-in follows you to every account and computer. [Download](https://shuriken.sh/download) ## Keep the tool list short # Codex offers every server's tools to the model. enabled_tools is an allow list and disabled_tools a deny list applied after it, so enabled_tools = ["open", "screenshot"] with disabled_tools = ["screenshot"] leaves only open. Claude Code has the same problem, and [too many MCP servers](https://shuriken.sh/guides/too-many-mcp-servers-context) measures what a long tool list costs in context. Each server can also say when its tools need your approval. default_tools_approval_mode takes auto, prompt, writes or approve; writes prompts for any tool not marked read-only. A [mcp_servers..tools.] table overrides it for one tool with approval_mode. ## When a server won't start # - It times out at startup. A first npx run can take longer than the timeout while it downloads the package. Raise startup_timeout_sec. The error message prints the limit in force, which in current Codex releases is longer than the 10 seconds OpenAI's page lists. - Codex starts without it. For servers that aren't required, Codex waits mcp_optional_startup_grace_ms (1000 milliseconds by default) while it builds the first tool list. Set it to 0 to wait for each server's full startup_timeout_sec. - A tool call times out. Raise tool_timeout_sec, for example for a long database query. - It fails to start or fails the handshake. [Codex MCP server failed to start](https://shuriken.sh/guides/codex-mcp-server-failed-to-start) goes through each error message and its fix. ## One list for Codex and Claude Code # OpenAI says the CLI, the IDE extension and the ChatGPT desktop app share this config, so a server added with codex mcp add also shows under Settings › MCP servers in the desktop app. Claude Code doesn't read it: its list lives in ~/.claude.json and .mcp.json, so a server you add here has to be added there too, sign-in and all. The Claude side is in [MCP servers across all projects](https://shuriken.sh/guides/mcp-servers-across-all-projects). Shuriken keeps one list of MCP servers, in Settings › Extensions › MCP servers, and hands it to every Codex and Claude Code chat in the projects you choose, when the chat starts. You sign in to a server once; the sign-in belongs to the server, not to your AI account, so switching accounts or projects doesn't ask again. A server already in your Codex config.toml appears in each project's MCP servers list marked All projects. Turning it off there writes enabled = false into that file, because Codex has no per-project switch for its own servers, so the change reaches every Codex chat in every project. For a starting list, we picked [MCP servers worth adding](https://shuriken.sh/blog/best-mcp-servers-for-claude-code). Share [X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-mcp-servers&text=How%20to%20add%20an%20MCP%20server%20to%20Codex%20CLI)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-mcp-servers)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-mcp-servers&t=How%20to%20add%20an%20MCP%20server%20to%20Codex%20CLI)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-mcp-servers&title=How%20to%20add%20an%20MCP%20server%20to%20Codex%20CLI)[E-mail](mailto:?subject=How%20to%20add%20an%20MCP%20server%20to%20Codex%20CLI&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-cli-mcp-servers) ## Sources - [OpenAI: Model Context Protocol in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) (accessed 25 October 2026) - [OpenAI: Codex config basics](https://learn.chatgpt.com/docs/config-file/config-basic) (accessed 23 October 2026) ## Frequently asked questions **How do I add an MCP server to Codex?** Run codex mcp add -- , for example codex mcp add context7 -- npx -y @upstash/context7-mcp. Or add a [mcp_servers.] table to ~/.codex/config.toml. **Does Codex support remote (HTTP) MCP servers?** Yes. Codex supports local servers started by a command (stdio) and remote Streamable HTTP servers at an address, with a url key in config.toml. **How do I sign in to an MCP server in Codex?** For a server that supports OAuth, run codex mcp login . You can ask for scopes with --scopes, for example --scopes read,write. **Do Claude Code and Codex share MCP servers?** No. Codex reads ~/.codex/config.toml; Claude Code reads ~/.claude.json and .mcp.json. You add each server to both, or use a tool that keeps one list for both. **How do I turn an MCP server off without deleting it?** Set enabled = false in its [mcp_servers.] table. Global MCPs One MCP list for every agent. Add an MCP server once, choose its projects and sign in once. Your Claude Code, Codex and Gemini CLI chats all get it. [Download](https://shuriken.sh/download) [Other platforms](https://shuriken.sh/download#main) ## Keep reading - [Two Notion workspaces, one MCP list: Story 27 Oct 2026 3 min read Add Notion twice, once for work and once for personal, each with its own sign-in, and pick which projects get which. Switching accounts never asks again.](https://shuriken.sh/blog/two-notion-accounts-one-mcp-list) - [Claude Code MCP server failed to connect: how to fix it: Guide 27 Oct 2026 6 min read Claude Code says Failed to connect when an MCP server never starts or answers. claude mcp get prints the error; a relative path is a frequent cause.](https://shuriken.sh/guides/claude-code-mcp-server-failed-to-connect) - [Claude Code MCP server timeout: the settings that fix it: Guide 27 Oct 2026 4 min read Claude Code MCP server timeout errors: the startup timeout for slow servers, a per-server limit for long tool calls, the idle window, and big output.](https://shuriken.sh/guides/claude-code-mcp-timeout) - [Claude Code across many projects: keep them apart: Guide 27 Oct 2026 6 min read Claude Code ties sessions, CLAUDE.md, settings and MCP servers to the folder you start it in. Run one session per project; put shared setup in user scope.](https://shuriken.sh/guides/claude-code-multiple-projects) - [Claude Code skills vs subagents vs MCP: which one to use: Guide 27 Oct 2026 6 min read Claude Code skills vs subagents: a skill is know-how in your chat, a subagent is work in its own context, MCP is a live outside system. One table to pick.](https://shuriken.sh/guides/claude-code-skills-vs-subagents) - [Migrate Claude Code to a new computer, settings and all: Guide 27 Oct 2026 8 min read To migrate Claude Code to another computer, copy ~/.claude without the login file, keep project paths the same so old chats resume, and sign in again.](https://shuriken.sh/guides/migrate-claude-code-to-new-computer) - [Set up Shuriken in your first hour: Guide 27 Oct 2026 5 min read Set up Shuriken in order: sign in, add a project, add your accounts and keys, choose when chats switch, add MCP servers once, then your phone and servers.](https://shuriken.sh/guides/set-up-shuriken) ## Free tools - [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) - [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)