Home · Learn · Codex MCP

How to Add an MCP Server to Codex CLI (With a Trading Example)

Updated November 2, 2026 · By Moby

To add an MCP server to Codex, run codex mcp add <name> -- <command> for a local STDIO server, or codex mcp add <name> --url <server-url> for a Streamable HTTP server. Codex saves it to ~/.codex/config.toml. Run codex mcp list, or type /mcp in the Codex terminal UI, to confirm the server is connected.

STDIO form from the Codex MCP guide. Everything after -- is the program Codex starts.

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

What MCP does in Codex

MCP (Model Context Protocol) lets Codex call tools on other systems. An MCP server describes the available tools and handles their requests. That line is from OpenAI's Codex MCP guide. The protocol is described in the Model Context Protocol introduction.

An OpenAI Codex MCP server is one of two types. STDIO servers run as a local process (started by a command). Streamable HTTP servers are servers that you access at an address, with bearer token or OAuth authentication, including Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR).

Context7, started with npx, is OpenAI's STDIO example. A hosted server is a URL. The Codex CLI and the Codex IDE extension both read config.toml. Claude Code's file is in the Claude Code MCP guide. Trading servers as their own topic are in MCP for trading.

Add an MCP server with the Codex CLI

codex mcp add is the command, whether you searched for codex mcp add or codex add mcp. For a local server, pass the name, any --env pairs, then -- and the program. OpenAI's guide uses Context7:

Context7, copied from the Codex MCP guide.

codex mcp add context7 -- npx -y @upstash/context7-mcp

Flags stay left of --. The server command stays to the right, so npx is not read as a Codex flag. Repeat --env KEY=VALUE once per variable. The CLI reference says --env applies to STDIO launches.

For Streamable HTTP, pass --url and no command. The CLI reference says --url registers a streamable HTTP server and cannot be combined with a STDIO command:

codex mcp add <server-name> --url https://example.com/mcp

If the server expects a bearer token, add --bearer-token-env-var and the name of an environment variable. The CLI reference says that variable's value is sent as the bearer token. Export it in the shell that starts Codex. Do not put the token in the command. The worked example uses this flag.

For OAuth, run codex mcp login <server-name>. On a headless terminal, add --no-browser, open the printed URL, and paste the full redirect URL back. --oauth-client-id and --oauth-client-secret are for a pre-registered client. The secret is saved in config.toml. Moby does not use OAuth.

codex mcp list shows stored servers, codex mcp get <name> shows one, and codex mcp --help lists subcommands, including remove. In the codex TUI, type /mcp. The IDE extension adds the same servers from the gear menu, under MCP servers. Source: the Codex CLI repo.

Configure MCP servers in config.toml

Codex MCP config lives in ~/.codex/config.toml. A project file, .codex/config.toml, loads only for trusted projects, per the config reference. codex mcp add writes the user file. Edit the project file when the server should exist only in that repo.

Each server is a [mcp_servers.<name>] table, named as in codex mcp add. Use command or url, not both.

bearer_token_env_var is the variable name, not the token. Codex sends that value in Authorization. A string in env_vars reads the local environment. source = "remote" needs remote MCP stdio, per the MCP guide. The config reference lists auth as oauth (the default) or chatgpt, and only after a bearer token or authorization header.

The Context7 command matches this table:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

The MCP guide's current Context7 example also sets optional environment keys:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

The config reference is the full list of config options, including startup_timeout_ms (the millisecond alias of startup_timeout_sec), required, and http_headers_helper.

Limit what the server can do

enabled_tools is an allow list of tool names from that server. disabled_tools is a deny list applied after enabled_tools, so a name that appears in both stays off. default_tools_approval_mode sets the default for every tool on the server. OpenAI documents four values: auto, prompt, writes, and approve. The MCP guide says the writes mode prompts for tools that aren't marked read-only. One tool can override the default with tools.<tool>.approval_mode.

startup_timeout_sec defaults to 10. tool_timeout_sec defaults to 60. Set enabled = false to switch a server off without deleting it. codex mcp remove <name> deletes the entry. The MCP guide puts several of these on one HTTP server:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

These client-side controls are useful, but for a server that can spend money you also want limits enforced on the server, which the next section shows. Until you know the server marks tools read-only, add "prompt" only.

Worked example: connect a trading MCP server (Moby)

Here is what this looks like with a server that can place trades. We use the Moby MCP because we built it. Codex trading here means Codex calls that server. The same codex mcp add command is the Codex step. The key and the check are the rest.

Moby Agents trade Solana tokens, paid in USDC, including tokenized stocks. The liquid names are AAPLx, MSFTx, GOOGLx, AMZNx, METAx, NVDAx, TSLAx, AVGOx, TSMx, COINx, MSTRx, CRCLx, SPYx, QQQx, and GLDx. AI Trading on Base, BNB Chain and Robinhood Chain is coming soon. The Moby app itself trades Solana, Base, BNB Chain and Robinhood Chain.

1. Create a key in the Moby app

   In the Moby app: Agent tab, then Connect, then create a key. It starts with moby_agent_. It is a revocable agent API key, not a wallet private key. Do not paste it into chat. You can revoke it in the app.

2. Export the key

   Set MOBY_API_KEY to the key itself, not the word Bearer, in the environment that starts Codex.

   Copy

   export MOBY_API_KEY="moby_agent_..."

3. Add the server

   The Moby MCP server is Streamable HTTP at https://mcp.moby.win/mcp, bearer auth, no OAuth. The flag is the one from the CLI reference:

   Copy

   codex mcp add moby --url https://mcp.moby.win/mcp --bearer-token-env-var MOBY_API_KEY

4. Read the table it writes

   That command writes ~/.codex/config.toml. The table is mcp_servers.moby. Codex sends Authorization: Bearer using the key from MOBY_API_KEY.

   Copy

   [mcp_servers.moby]
   url = "https://mcp.moby.win/mcp"
   bearer_token_env_var = "MOBY_API_KEY"

5. Confirm, then start

   Run codex mcp list, or type /mcp, and look for moby. On first connect, ask Codex to call get_my_trading_profile. The full Moby setup for Codex is the page that covers that first run. This guide stops at the connection.

Optional: set default_tools_approval_mode to "prompt" if you want Codex to ask before each tool call.

[mcp_servers.moby]
url = "https://mcp.moby.win/mcp"
bearer_token_env_var = "MOBY_API_KEY"
default_tools_approval_mode = "prompt"

A buy spends USDC, and only after you say yes.

Check risk before a buy

Check the risk of this Solana token before I buy it with USDC. Tell me if I should skip it.

Scan smart money

Scan Solana smart-money flows. List tokens tracked wallets are buying. Do not buy anything.

Guarded buy

If this Solana token fits my limits, prepare a buy of 10 USDC. Name the token, the contract, and the amount, and wait for my yes.

Set up your Moby Agent

Why server-side limits matter here

You set your agent's limits on max per trade, daily buy volume and market-cap range from the Moby app, and Moby checks them server-side on every buy your agent makes. The agent has its own wallet, separate from your main in-app wallet. There are no withdrawals through MCP. A profile saved by Codex cannot raise the app limits. Moby refuses agent buys on tokens it rates red. The tiers are green, grey, and red. Rate limits are up to 6 trades a minute and 200 a day. How those checks are built is covered under AI agent guardrails.

Troubleshooting Codex MCP

• Server not listed. Run codex mcp list. Check the server name in config.toml, and check that enabled is not false. codex mcp get <name> shows the single entry the list is reading.
• Times out on start. Raise startup_timeout_sec. The default is 10.
• 401 or unauthorized on an HTTP server. The environment variable named in bearer_token_env_var is not set in the shell that launched Codex. Export it there, then start Codex again. codex mcp list only reads the file, so it can still show the server.
• Project-only install not loading. A project .codex/config.toml loads only for trusted projects. If the project is untrusted, Codex skips that file and the server never appears.
• Windows. STDIO servers have known Windows reports. The thread is a report, not a fix.

Frequently asked questions

Does Codex support MCP?

Yes. Codex supports MCP servers in the Codex CLI and the Codex IDE extension. It works with local STDIO servers started by a command and with Streamable HTTP servers reached at a URL, using a bearer token or OAuth for authentication.

How do I add an MCP server to Codex?

Run codex mcp add followed by a name. For a local server, add two dashes and the command that starts it, for example codex mcp add context7 -- npx -y @upstash/context7-mcp. For a hosted server, pass --url with the server address. Then run codex mcp list to check it.

Where is the Codex MCP config file?

Codex stores MCP settings in ~/.codex/config.toml. Each server gets its own [mcp_servers.name] table. You can also scope servers to one project with .codex/config.toml in that project, which Codex only loads for trusted projects.

How do I pass an API key to an MCP server in Codex?

For a Streamable HTTP server, set bearer_token_env_var to the name of an environment variable that holds the token, then export that variable before you start Codex. This keeps the token out of config.toml. For STDIO servers, use env or env_vars.

How do I see which MCP servers Codex is using?

Run codex mcp list in your terminal, or type /mcp inside the Codex terminal UI to see the active servers. If a server is missing, check its name in config.toml and make sure enabled is not set to false.

Can I limit which MCP tools Codex can call?

Yes. Use enabled_tools as an allow list and disabled_tools as a deny list for each server. You can also set default_tools_approval_mode to prompt so Codex asks before calling a tool, or set an approval mode per tool.

Can Codex trade crypto through MCP?

Codex can call a trading MCP server if you connect one. With the Moby MCP, a Moby Agent researches and trades Solana tokens, paid in USDC, including tokenized stocks, inside the limits you set in the Moby app. It has its own wallet and cannot withdraw funds.

Is it safe to connect a trading MCP server to Codex?

It depends on the limits behind it. With Moby, you set your agent's limits on max per trade, daily buy volume and market-cap range from the Moby app, and Moby checks them server-side on every buy your agent makes. Trading is risky and you can lose money.

Try it with a Moby Agent

Commands and keys checked against the Codex MCP guide, the CLI reference, and the config reference on November 2, 2026.