AI Coding Guide

Allow only some tools from an MCP server in Codex: enabled_tools, timeouts, and approval modes

Codex Published:

Restrict which tools an MCP server exposes to Codex with enabled_tools and disabled_tools, tune startup_timeout_sec and tool_timeout_sec, and require approval before tools run.

Verified on Sep 10, 2026 These tools change quickly. Please also check the latest official documentation.
#Codex#MCP#config.toml#enabled_tools#tool_timeout_sec
Contents
  1. Narrowing the tool set
  2. Tuning timeouts
  3. Approvals and output limits
  4. Summary

Adding an MCP server gives Codex every tool that server exposes. Often you want only some of them: with a browser server, for example, screenshots yes, form submission no.

In short: enabled_tools and disabled_tools under [mcp_servers.<id>] narrow the tool set, default_tools_approval_mode and tools.<tool>.approval_mode require confirmation before a tool runs, and startup_timeout_sec and tool_timeout_sec control how long Codex waits.

KEY POINT

What you will learn

  • Writing tool allowlists and denylists
  • Default startup and tool timeouts, and how to change them
  • Approval modes and per-tool output token limits

Narrowing the tool set

The official example, for an HTTP server: allow open and screenshot, then deny screenshot.

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
KeyMeaning
enabled_toolsallowlist of tool names
disabled_toolsdenylist of tool names
enabledfalse disables the server without deleting its config
requiredtrue makes Codex fail to start if the server cannot initialize

Use the tool names exactly as the server publishes them; codex mcp list shows configured servers.

用語解説

stdio and HTTP servers: a stdio server is launched as a process with command and args; an HTTP (streamable) server is reached through url. Tool filtering and timeouts apply to both.

Tuning timeouts

KeyDefaultMeaning
startup_timeout_sec10 show long to wait for the server to start; startup_timeout_ms for milliseconds
tool_timeout_sec60 show long to wait for a single tool call

A server that fetches a package through npx on every launch, or spins up a browser the first time, can miss the 10-second window. If a silent skip is unacceptable, set required = true so the failure is explicit.

The grace period for optional servers (those without required) is the global mcp_optional_startup_grace_ms, default 1000 ms.

Approvals and output limits

default_tools_approval_mode sets the server-wide approval behavior: auto, prompt, writes, or approve. Individual tools can override it under [mcp_servers.<id>.tools.<tool>].

[mcp_servers.docs]
command = "npx"
args = ["-y", "some-docs-mcp"]
enabled_tools = ["search", "summarize"]
default_tools_approval_mode = "auto"

[mcp_servers.docs.tools.summarize]
approval_mode = "prompt"
output_token_limit = 30000

output_token_limit caps the tokens a tool's output may occupy, which keeps search-style tools from flooding the context. For a limit across all tool outputs, use the top-level tool_output_token_limit.

Pass secrets through env and env_vars, not literals

For stdio servers, set values under [mcp_servers.<id>.env] or list names to forward with env_vars = ["LOCAL_TOKEN"]. For HTTP servers, name the variable holding the token with bearer_token_env_var. Do not write token values into config.toml.

The relationship to approval policy is part of the hub article Configuring Codex with config.toml, and the safety model in Codex approval modes and sandbox settings.

Summary

  • enabled_tools / disabled_tools narrow a server's tools
  • Startup waits startup_timeout_sec (default 10 s), tool calls tool_timeout_sec (default 60 s); use required = true for must-have servers
  • default_tools_approval_mode and tools.<tool>.approval_mode require confirmation before a tool runs
  • output_token_limit caps a tool's output tokens
  • Pass tokens via bearer_token_env_var or env_vars, never as literals

FAQ

What happens if I set both enabled_tools and disabled_tools?
The official example sets both, with disabled_tools removing entries from the enabled_tools allowlist. If one list is enough, use just one for readability.
My MCP server starts slowly and gets skipped.
Raise startup_timeout_sec (default 10 seconds). For a server you cannot work without, set required = true so Codex fails to start instead of silently continuing.
Can I require confirmation for one specific tool?
Yes, with approval_mode under [mcp_servers.<id>.tools.<tool>]. For the whole server, use default_tools_approval_mode.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles