Blog

Codex | 7 min read | 2026-08-27 | By Variant Team

How to add an MCP server to Codex: HTTP and stdio setup

Learn how to add an MCP server to Codex over HTTP or stdio, inspect the generated config, authenticate, verify the connection, and fix common errors.

Author: Variant Team. Variant is built by a small team working on HTML-native presentation tools, MCP workflows, and agent-editable decks.

To add an MCP server to Codex, first determine whether the server uses streamable HTTP or runs as a local stdio process. The command differs by transport, but Codex stores both kinds in the same configuration file.

The fastest path is codex mcp add. You can also edit ~/.codex/config.toml directly.

#Quick answer

Run codex mcp add <name> --url <url> for a streamable HTTP server. Run codex mcp add <name> -- <command> <args> for a stdio server. Then use codex mcp list or codex mcp get <name> --json to confirm that Codex saved the server.

#Choose HTTP or stdio

An HTTP MCP server runs at a URL. The provider hosts it, and Codex connects over the network. Authentication may happen through OAuth or a bearer token.

A stdio MCP server is a command that Codex starts on your computer. Codex exchanges MCP messages with that process through standard input and output. Local filesystem and developer-tool integrations often use this model.

Use the transport documented by the MCP server provider. An HTTP URL cannot be added as the command after --, and a local executable does not belong in the --url form.

#Add an HTTP MCP server

The HTTP form needs a short local name and the server URL:

codex mcp add <name> --url <url>

For example, Variant hosts a presentation MCP server at https://mcp.variant.art/mcp:

codex mcp add variant --url https://mcp.variant.art/mcp

The name variant identifies this connection in later commands. You will use it with get, login, logout, and remove.

After the command succeeds, Codex writes an entry like this to ~/.codex/config.toml:

[mcp_servers.variant]
url = "https://mcp.variant.art/mcp"

This is a streamable HTTP connection. You do not need to install or keep a local server process running.

#Add a stdio MCP server

The stdio form uses -- to separate Codex options from the command that starts the server:

codex mcp add <name> -- <command> <args>

Here is a local filesystem server launched through npx. Replace the final path with an absolute directory that the server may access:

codex mcp add local-files -- npx -y @modelcontextprotocol/server-filesystem /absolute/path/to/project

Codex records the executable separately from its arguments. The resulting configuration has this shape:

[mcp_servers.local-files]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/to/project"]

The directory is part of the server's access boundary, so do not point it at a broader location than the task requires.

#Edit config.toml by hand

Direct editing is useful when you manage dotfiles or need to inspect a broken entry. Codex reads MCP server definitions from ~/.codex/config.toml. If CODEX_HOME is set, Codex uses that directory instead.

Each server gets its own [mcp_servers.<name>] table. An HTTP server uses url:

[mcp_servers.example_http]
url = "https://example.com/mcp"
startup_timeout_sec = 20

A stdio server uses command and an array of args. Environment variables go in a child table:

[mcp_servers.example_stdio]
command = "npx"
args = ["-y", "example-mcp-package"]
startup_timeout_sec = 20

[mcp_servers.example_stdio.env]
EXAMPLE_API_KEY = "replace-with-your-value"

startup_timeout_sec changes how long Codex waits for startup. Add it only when the server needs more time than the default. Keep secrets out of files that you commit, and use the server's documented environment variable names.

When you use the CLI for a stdio server, --env KEY=VALUE adds an environment variable. That flag applies to stdio servers only. For an HTTP server, use its OAuth flow or the bearer-token option described below.

#Verify the saved server

List all configured servers after adding one:

codex mcp list

Codex prints separate stdio and HTTP tables. The Status column shows whether an entry is enabled. The Auth column describes authentication state. For an OAuth-capable HTTP server, Auth reads Not logged in until you authenticate with codex mcp login <name>.

To inspect one entry as structured output, run:

codex mcp get variant --json

Replace variant with the name you chose. The JSON form shows which URL, command, arguments, or environment settings Codex loaded.

If codex mcp itself is unavailable, run codex --version and check how your Codex installation should be updated. codex doctor can diagnose installation, configuration, and authentication problems.

#Authenticate an HTTP server

For an HTTP server that supports OAuth, start the login flow by name:

codex mcp login variant

Complete the sign-in in the browser, then run codex mcp list again. The authentication state should no longer read Not logged in. Some servers accept requested scopes through codex mcp login <name> --scopes a,b; use only scopes documented by the provider.

For a headless environment or CI job, Codex can read a bearer token from an environment variable when you add the HTTP server:

codex mcp add example --url https://example.com/mcp --bearer-token-env-var EXAMPLE_MCP_TOKEN

Set EXAMPLE_MCP_TOKEN in the process environment before starting Codex. The option names the environment variable. It does not contain the token itself. This keeps the secret out of config.toml.

For redirect, token, or browser-login failures, use the focused Codex MCP OAuth troubleshooting guide. The Codex MCP documentation covers the Variant connection in a shorter reference format.

#Remove or replace a server

Remove an entry by its configured name:

codex mcp remove variant

If a URL or command changed, removing and adding the entry again is often clearer than leaving stale keys in config.toml. Run codex mcp get <name> --json afterward to confirm the new definition.

#It did not work

Start with the smallest check that matches the symptom.

Authentication problems can look like connection problems. Check Codex MCP OAuth troubleshooting before changing a valid server URL. For a broader explanation of transports and presentation tools, read what an MCP server for presentations does.

#End-to-end example with Variant

Variant is useful when you want Codex to create a presentation that remains editable. Every slide is HTML and CSS, and Variant's MCP tools let Codex create a deck, inspect slides, make targeted edits, preview the result, and export it.

First, add the hosted server:

codex mcp add variant --url https://mcp.variant.art/mcp

Next, authenticate:

codex mcp login variant

Variant uses OAuth by default. The first MCP request can also open the browser sign-in flow. After login, verify the entry:

codex mcp get variant --json

Then start Codex and give it a concrete request. For example:

Use Variant's MCP tools to create a six-slide product strategy deck for a developer tool. Include a title slide, the user problem, the proposed workflow, an architecture diagram, a rollout plan, and a final decision slide. Use a restrained dark theme, preview each slide, and fix any text overflow before returning the deck link.

The deck comes back as HTML slides that you can keep editing through Codex or on Variant's visual canvas. You can later export the deck as single-file HTML, PDF, PPTX, or JSON. The guide to using Codex for editable presentation decks covers the authoring loop in more detail, while the MCP tools reference lists the available presentation operations.

Variant is not the right MCP server for every task. Use a filesystem server when Codex needs controlled access to local files. Use a database or issue-tracker server when that system is the real source of truth. Choose Variant when the artifact you want Codex to create and revise is a slide deck.

#Related reading

• Use Codex to generate editable presentation decks
• Codex MCP configuration reference
• Variant MCP setup documentation

#FAQ

#What command adds an MCP server to Codex?

Use codex mcp add <name> --url <url> for a streamable HTTP server. Use codex mcp add <name> -- <command> <args> for a local stdio server.

#Where does Codex store MCP server configuration?

Codex stores MCP server entries in ~/.codex/config.toml under [mcp_servers.<name>]. If CODEX_HOME is set, Codex uses the configuration file in that directory instead.

#How do I know whether an MCP server uses HTTP or stdio?

Check the server provider's setup instructions. A hosted endpoint beginning with https:// normally uses the HTTP form, while a package or executable that Codex starts locally uses the stdio form.

#Why does codex mcp list say Not logged in?

Not logged in means an HTTP server has not completed its OAuth flow. Run codex mcp login <name>, finish the browser sign-in, and check codex mcp list again.

#Can Codex use an MCP server in CI without browser login?

Yes, if the HTTP server supports bearer-token authentication. Add it with --bearer-token-env-var <ENV_VAR> and provide the token through that environment variable in the CI process.

#How do I remove an MCP server from Codex?

Run codex mcp remove <name> with the same local name used when the server was added. Confirm removal with codex mcp list.

#The short version

Use --url for an HTTP MCP server and place a local command after -- for a stdio server. Codex saves both in ~/.codex/config.toml, where you can inspect or edit the matching server table. Verify the result with codex mcp list, and run codex mcp login <name> when an HTTP server shows Not logged in. Variant is a good choice when Codex needs to create editable HTML slide decks, but a server tied to your actual files, database, or issue tracker is better for those systems.