Configure MCP in Codex: HTTP, local servers, and connection checks

Identify the transport first

MCP provides tools and external information; it is separate from the model API. A service URL usually means Streamable HTTP. An executable plus arguments means STDIO. Do not use a website homepage or model Base URL as an MCP endpoint.

Start with one HTTP connection

[mcp_servers.team_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TEAM_DOCS_TOKEN"
enabled = true

The address is a placeholder. Remove bearer_token_env_var if the service does not use bearer authentication. For OAuth-enabled services, run codex mcp login team_docs. MCP credentials and model-provider credentials serve different purposes.

codex mcp list
codex mcp --help

STDIO depends on the launch environment

[mcp_servers.local_docs]
command = "/absolute/path/to/your-mcp-server"
args = ["--stdio"]
env_vars = ["TEAM_DOCS_TOKEN"]
startup_timeout_sec = 20

This does not install a server. Use a trusted installed executable and its actual arguments. A command available in a terminal may be missing from the graphical client’s PATH; an absolute path can make that distinction clearer.

Verify tool discovery and one call

1. Save the configuration and reconnect. Use the client’s Restart control when available, or start a fresh CLI session.
2. Check configured servers with codex mcp list and session tools with /mcp.
3. Request one read-only operation, such as retrieving a public document title, naming the intended service.
4. Confirm the result came from the tool and match it against the service request, rather than accepting a memory-based answer.

Diagnose the failing stage

startup_timeout_sec and tool_timeout_sec address different stages. Raise a limit only when the service genuinely needs more time; longer waits do not repair a bad endpoint.

Expand deliberately

If using enabled_tools, copy actual tool names exposed by the server. Set enabled = false to disable a connection without deleting your configuration. A read-only local filesystem does not automatically make remote MCP tools read-only. Continue with permissions and approvals or the configuration library.