Guide · checked 24 October 2026

How to add an MCP server to Codex Worked example: posting to social media from Codex

Codex reads MCP servers from ~/.codex/config.toml. Add a remote one with codex mcp add <name> --url <url>, then sign in with codex mcp login or point bearer_token_env_var at an API key. The Codex CLI, the IDE extension and the ChatGPT desktop app all use the same file.

Add a server See the social media example

terminal

# Remote server, OAuth sign-in
codex mcp add upload-post --url https://mcp.upload-post.com/mcp
codex mcp login upload-post

# Or the same server with an API key from an environment variable
codex mcp add upload-post --url https://mcp.upload-post.com/mcp \
  --bearer-token-env-var UPLOAD_POST_API_KEY

codex mcp list

Two ways to add a server

The CLI command writes the same table you could write by hand.

The minimum in config.toml

config.toml

# ~/.codex/config.toml
[mcp_servers.upload-post]
url = "https://mcp.upload-post.com/mcp"

Save it, start Codex and run codex mcp login upload-post once. A local server uses command and args instead of url.

With an API key and a trimmed tool list

config.toml

[mcp_servers.upload-post]
url = "https://mcp.upload-post.com/mcp"
bearer_token_env_var = "UPLOAD_POST_API_KEY"
enabled_tools = ["list_users", "upload_video", "upload_photos",
                 "upload_text", "get_status", "list_scheduled"]
startup_timeout_sec = 20
tool_timeout_sec = 120

Export UPLOAD_POST_API_KEY in your shell or CI secret store; never put the key itself in the file.

The settings that matter

From OpenAI’s Codex MCP docs, read 24 October 2026.

Key	What it does
`url`	The server’s streamable HTTP endpoint. Use command and args instead for a local stdio server.
`bearer_token_env_var`	Name of an environment variable whose value is sent as a Bearer token.
`http_headers / env_http_headers`	Static headers, or headers whose values come from environment variables.
`enabled_tools / disabled_tools`	Keep only the tools you need, so the model sees a shorter list.
`startup_timeout_sec`	How long Codex waits for the server to start. Default 10.
`tool_timeout_sec`	How long one tool call may run. Default 60; raise it for uploads.

Sign-in	How	Best for
OAuth	codex mcp login <name>; a browser tab opens and Codex stores the token	Your own machine
Bearer token from an env var	bearer_token_env_var = "NAME", or --bearer-token-env-var on mcp add	CI, servers, shared machines
Custom headers	http_headers or env_http_headers, for servers that want another header	Servers with their own scheme

Source: Codex MCP documentation.

Worked example: post to social media from Codex

Upload-Post’s MCP server publishes to TikTok, Instagram, YouTube, LinkedIn, X and more. Add it as above, connect your accounts once at app.upload-post.com, then ask.

Release posts

“Read CHANGELOG.md and write a LinkedIn post and an X post about today’s release. Schedule both for 9:00 tomorrow, New York time.”

Video

“Post the demo video at this link to TikTok and YouTube Shorts with the same caption.”

Scheduling

“List my scheduled posts for next week and move the Friday one to Monday.”

Analytics

“Which of last month’s posts got the most views on each network?”

Codex shows each tool call before running it. Media should be a public link (S3, R2, Google Drive), the simplest input for a hosted server. Comparing servers? See the best social media MCP servers.

The same server in Cursor

Cursor reads .cursor/mcp.json in the project or ~/.cursor/mcp.json for every project. A remote server needs only url; Cursor signs in with OAuth when the server supports it, or sends the headers you set, with ${env:NAME} taken from your environment.

Step by step for Cursor, with example prompts: post to social media from Cursor.

mcp.json

// .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
  "mcpServers": {
    "upload-post": {
      "url": "https://mcp.upload-post.com/mcp",
      "headers": { "Authorization": "ApiKey ${env:UPLOAD_POST_API_KEY}" }
    }
  }
}

Three things older guides get wrong

Codex’s MCP support has changed quickly; these still show up in search results.

You may read	What the docs say now
Codex only supports local stdio servers	Codex connects to remote streamable HTTP servers too, with OAuth or a bearer token.
You run Codex as an MCP server with codex mcp-server	That subcommand was removed. Codex is the client; the server is the tool you add.
The CLI and the IDE extension need separate setups	They read the same config.toml, and so does the ChatGPT desktop app.

When the server does not work

The problems people hit first, and the fix for each.

Every tool call fails with 401

Codex has no credentials for the server. Run codex mcp login <name>, or set the environment variable that bearer_token_env_var names before you start Codex.

The server does not show up

Run codex mcp list. A project file at .codex/config.toml only loads in a trusted project; the global file is ~/.codex/config.toml.

Codex times out while the server starts

Raise startup_timeout_sec. For uploads of large media, also raise tool_timeout_sec.

The model picks the wrong tool

Trim the list with enabled_tools so only the tools you use are visible.

The OAuth tab never opens

Codex listens on a local loopback address for the callback. Check that a firewall or proxy is not blocking it, or use the bearer token route.

Upload-Post returns 401 with a key

Use a current Upload-Post API key. On the MCP endpoint it is accepted as Bearer or as ApiKey.

Codex and MCP: frequently asked questions

How do I add an MCP server to Codex?

Run codex mcp add <name> --url <server-url> for a remote server, then codex mcp login <name> if it uses OAuth. Or add a [mcp_servers.<name>] table with url = "..." to ~/.codex/config.toml. Check it with codex mcp list.

Where is Codex’s config.toml?

In ~/.codex/config.toml for your user. A project can also have .codex/config.toml, which Codex loads only when you trust that project.

Does Codex support remote MCP servers and OAuth?

Yes. Codex talks to streamable HTTP servers and signs in with OAuth through codex mcp login, or sends a bearer token taken from an environment variable.

Do the Codex CLI, the IDE extension and the ChatGPT app share MCP servers?

Yes. They read the same config.toml, so a server you add once is available in all of them.

Can Codex run as an MCP server?

Not any more: the codex mcp-server subcommand was removed. Codex is the MCP client.

How do I let Codex post to social media?

Add a social media MCP server such as Upload-Post (https://mcp.upload-post.com/mcp), sign in, and ask in plain English: “write a LinkedIn post from CHANGELOG.md and schedule it for 9:00 tomorrow”. Codex calls the server’s publishing tools.

How do I add the same server to Cursor?

Put it in .cursor/mcp.json or ~/.cursor/mcp.json with "url", and either let Cursor sign in with OAuth or add an Authorization header that reads the key from ${env:NAME}.

Should I use OAuth or an API key?

OAuth on your own machine, because there is no secret to store. An API key in an environment variable for CI, servers and shared machines.

Give Codex a social media server

Free Upload-Post plan, no card. One server for TikTok, Instagram, YouTube, LinkedIn, X and more.

Start free About the MCP server

Schedule posts with Claude Code Cursor for social media Best social media MCP servers ChatGPT for social media Post from GitHub Actions