MCP in practice: connecting AI agents to your internal tools

An AI coding agent that can only read files and run shell commands is useful. An agent that can search your documentation, inspect your Figma designs, control a browser, query your logs, and manage GitHub issues is something else entirely. The difference is MCP.

Model Context Protocol connects models to external tools and context through a standardized server interface. Codex supports it in both the CLI and IDE extension, with shared configuration so you set it up once and use it everywhere.

The two transport types

MCP servers come in two flavors, and the choice matters for how you configure, secure, and operate them:

STDIO servers launch as child processes. Codex starts them, communicates over standard I/O, and tears them down. They’re local, fast, and require no network configuration.

Streamable HTTP servers run at an address. Codex connects over HTTP. They can be local (localhost:3000) or remote (https://mcp.figma.com/mcp). Remote servers support OAuth login via codex mcp login.

Configuring STDIO servers

The simplest configuration is a command and optional arguments:

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

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

Add with the CLI:

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

Advanced STDIO options:

[mcp_servers.my-server]
command = "python3"
args = ["-m", "my_mcp_server"]
cwd = "/path/to/server"
startup_timeout_sec = 20
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

env_vars can be plain variable names (read from Codex’s local environment) or objects with source = "remote" (read from a remote executor environment). cwd sets the working directory for the server process.

Configuring Streamable HTTP servers

HTTP servers need at minimum a URL:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Authentication options:

• Bearer token — bearer_token_env_var points to an environment variable containing the token. Codex sends it as Authorization: Bearer <token>.
• OAuth — Run codex mcp login <server-name> for servers that support OAuth. Codex handles the full flow.
• Static headers — http_headers for fixed values, env_http_headers for values pulled from environment variables.

Tool filtering: allowlists and denylists

Not every tool an MCP server exposes is safe or relevant. Filter with enabled_tools and disabled_tools:

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

disabled_tools is applied after enabled_tools, so you can allowlist a broad set and then remove one. If you allowlist ["open", "screenshot"] and denylist ["screenshot"], only open is available.

enabled toggles the entire server off without removing its config. required = true makes startup fail if the server can’t initialize — use for critical infrastructure servers.

Timeout tuning

Two timeout controls matter:

• startup_timeout_sec — How long Codex waits for the server to start. Default 10 seconds. Raise for servers that do heavy initialization.
• tool_timeout_sec — How long Codex waits for a single tool call. Default 60 seconds. Lower for fast queries, raise for long-running operations like browser screenshots.

Six MCP servers worth configuring today

Each gives the agent a new sense. Context7 gives it docs. Figma gives it design. Playwright gives it a browser. Sentry gives it production telemetry. GitHub gives it project management. Together they close the gap between “writes code” and “operates as a team member.”

Project-scoped vs. user-scoped config

MCP config lives alongside other Codex settings in config.toml. User-level at ~/.codex/config.toml applies everywhere. Project-scoped at .codex/config.toml applies only in that repo:

~/.codex/config.toml        → personal MCP servers (Context7, your Playwright)
  <repo>/.codex/config.toml → project MCP servers (team Figma, shared Sentry)

The CLI and IDE extension share this configuration. Configure once, use in both surfaces. Project-scoped config loads only in trusted projects.

Debugging MCP servers

Common failure modes and fixes:

• Server doesn’t start — Check startup_timeout_sec. Some servers need more than 10 seconds. Verify the command and args are correct.
• Tool calls timeout — Raise tool_timeout_sec. Some operations (browser screenshots, large queries) need more than 60 seconds.
• Auth fails — For bearer tokens, verify the env var name matches. For OAuth, re-run codex mcp login <name>.
• Server appears but tools are missing — Check enabled_tools/disabled_tools. The allowlist might be filtering everything.
• Server works in CLI but not IDE — The config is shared, so this is usually a restart issue. Restart both surfaces.

Run codex mcp --help for the full CLI management surface, and use /mcp in the TUI to see active servers.