mcp.md Codex Docs, 2026-03-07 00:33 UTC → 2026-05-18 22:01 UTC

58- `env` (optional): Environment variables to set for the server.58- `env` (optional): Environment variables to set for the server.

59- `env_vars` (optional): Environment variables to allow and forward.59- `env_vars` (optional): Environment variables to allow and forward.

60- `cwd` (optional): Working directory to start the server from.60- `cwd` (optional): Working directory to start the server from.

61- `experimental_environment` (optional): Set to `remote` to start the stdio

62 server through a remote executor environment when one is available.

63 

64`env_vars` can contain plain variable names or objects with a source:

65 

66```toml

67env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

68```

69 

70String entries and `source = "local"` read from Codex's local environment.

71`source = "remote"` reads from the remote executor environment and requires

72remote MCP stdio.

61 73 

62#### Streamable HTTP servers74#### Streamable HTTP servers

63 75 

74- `required` (optional): Set `true` to make startup fail if this enabled server can't initialize.86- `required` (optional): Set `true` to make startup fail if this enabled server can't initialize.

75- `enabled_tools` (optional): Tool allow list.87- `enabled_tools` (optional): Tool allow list.

76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).88- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).

89- `default_tools_approval_mode` (optional): Default approval behavior for

90 tools from this server. Supported values are `auto`, `prompt`, and

91 `approve`.

92- `tools.<tool>.approval_mode` (optional): Per-tool approval behavior override.

77 93 

78If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.94If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.

79 95 

80If your MCP OAuth flow must use a specific callback URL (for example, a remote devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on loopback; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.96If your MCP OAuth flow must use a specific callback URL (for example, a remote Devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on the local interface; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

97 

98If the MCP server advertises `scopes_supported`, Codex prefers those

99server-advertised scopes during OAuth login. Otherwise, Codex falls back to the

100scopes configured in `config.toml`.

81 101 

82#### config.toml examples102#### config.toml examples

83 103 

85[mcp_servers.context7]105[mcp_servers.context7]

86command = "npx"106command = "npx"

87args = ["-y", "@upstash/context7-mcp"]107args = ["-y", "@upstash/context7-mcp"]

108env_vars = ["LOCAL_TOKEN"]

88 109 

89[mcp_servers.context7.env]110[mcp_servers.context7.env]

90MY_ENV_VAR = "MY_ENV_VALUE"111MY_ENV_VAR = "MY_ENV_VALUE"

108url = "http://localhost:3000/mcp"129url = "http://localhost:3000/mcp"

109enabled_tools = ["open", "screenshot"]130enabled_tools = ["open", "screenshot"]

110disabled_tools = ["screenshot"] # applied after enabled_tools131disabled_tools = ["screenshot"] # applied after enabled_tools

132default_tools_approval_mode = "prompt"

111startup_timeout_sec = 20133startup_timeout_sec = 20

112tool_timeout_sec = 45134tool_timeout_sec = 45

113enabled = true135enabled = true

136 

137[mcp_servers.chrome_devtools.tools.open]

138approval_mode = "approve"

139```

140 

141### Plugin-provided MCP servers

142 

143Installed plugins can bundle MCP servers in their plugin manifest. Those

144servers are launched from the plugin, so user config doesn't set their

145transport command. User config can still control on/off state and tool policy

146under `plugins.<plugin>.mcp_servers.<server>`.

147 

148```toml

149[plugins."sample@test".mcp_servers.sample]

150enabled = true

151default_tools_approval_mode = "prompt"

152enabled_tools = ["read", "search"]

153 

154[plugins."sample@test".mcp_servers.sample.tools.search]

155approval_mode = "approve"

114```156```

115 157 

116## Examples of useful MCP servers158## Examples of useful MCP servers

117 159 

118The list of MCP servers keeps growing. Here are a few common ones:160The list of MCP servers keeps growing. Here are a few common ones:

119 161 

120- [OpenAI Docs MCP](/resources/docs-mcp): Search and read OpenAI developer docs.162- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp): Search and read OpenAI developer docs.

121- [Context7](https://github.com/upstash/context7): Connect to up-to-date developer documentation.163- [Context7](https://github.com/upstash/context7): Connect to up-to-date developer documentation.

122- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/): Access your Figma designs.164- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/): Access your Figma designs.

123- [Playwright](https://www.npmjs.com/package/@playwright/mcp): Control and inspect a browser using Playwright.165- [Playwright](https://www.npmjs.com/package/@playwright/mcp): Control and inspect a browser using Playwright.