How to set up MCP servers for Codex

MCP (Model Context Protocol) servers give your AI coding assistant access to external tools and context, like your database schema or API docs. Codex reads them from its own config.toml, and you add them by hand. CodexUse has no MCP screen. What it gives you is one Codex home per profile, so a server you add for one account never starts under another.

What MCP servers do

MCP servers extend what your AI coding CLI can see and do:

• Database context: Connect to Postgres, MySQL, or SQLite to give the AI your schema.
• API documentation: Serve your internal API docs so the AI knows your endpoints.
• File system access: Provide access to specific directories or file types.
• Custom tools: Run scripts, queries, or commands the AI can invoke.

Where the configuration lives

Codex reads MCP servers from the config.toml in its home directory. On a plain Codex install that is ~/.codex/config.toml. Under CodexUse each profile gets its own Codex home, so each profile has its own config.toml and its own server list. Adding a server to one profile leaves the others untouched.

Adding a server

1. Open the config.toml of the profile you want the server in.
2. Add an [mcp_servers.NAME] block. NAME is the label Codex shows for the server.
3. For a local server, set command and args. Add env for credentials and cwd if the server needs a working directory.
4. For a remote server, set url instead of command.
5. Save the file, then start a new Codex session. Codex reads the config at session start.

Example: file system server

To expose one directory to Codex:

[mcp_servers.docs-folder]
command = "npx"
args = ["-y", "MCP_SERVER_PACKAGE", "/Users/you/Documents/docs"]

Replace MCP_SERVER_PACKAGE with the MCP server package you want to run.

Example: database server with a credential

[mcp_servers.postgres-dev]
command = "npx"
args = ["-y", "MCP_SERVER_PACKAGE"]

[mcp_servers.postgres-dev.env]
DATABASE_URL = "postgres://localhost:5432/dev"

Keep credentials in env rather than in args, and use a development database, not a production one.

Turning a server off

There is no toggle to click. Set enabled = false in the block and the server stays in the file without starting:

[mcp_servers.postgres-dev]
enabled = false
command = "npx"
args = ["-y", "MCP_SERVER_PACKAGE"]

Deleting the block removes the server outright.

Troubleshooting MCP servers

Symptom	Likely cause	Action
Server not starting	Command not found in PATH	Use full path to the executable or ensure npx is available
Codex can’t see the server	Block missing from the config Codex is reading, or enabled = false	Confirm you edited the config.toml of the profile you are running
Permission denied errors	File or DB not readable	Check file permissions on the target resource
Changes not taking effect	CLI session still running	Restart the CLI session to pick up new config
Server appears in the wrong account	Block added to a shared or default Codex home	Add it to the profile’s own Codex home instead

Common MCP server types

• SQLite: Query local databases
• Postgres: Query remote or local Postgres
• Filesystem: Read files in directories
• Git: Access git history and diffs
• Fetch: Make HTTP requests

Package names vary by server. Use the package name from the MCP server you want to run.

Best practices

• Name servers descriptively: “prod-db” vs “dev-db” helps you keep track.
• Remove servers you do not use: every running server uses resources and tokens.
• Test commands first: run the command in your terminal before you add it to the config.
• Use environment variables: put credentials in env, not in args.
• Keep profiles apart: add a client’s servers to that client’s profile only.

Related