codex-mmo/docs/TOOL_MCP.md

Tool MCP Servers

Codex MMO distinguishes two unrelated uses of MCP:

• Agent MCP is the internal mmo_mesh server that launches and supervises profile participants.
• Tool MCP connects Codex agents to third-party tools and context, such as a web-research service or a reverse-engineering application.

mmo_mesh is runtime-owned and reserved. Tool MCP definitions use operator-owned registry files; profile packs contain grants only. This keeps installed profile packs static and prevents one from introducing a local executable or remote endpoint.

Codex MMO compiles tool definitions to Codex's documented [mcp_servers.NAME] configuration. Codex 0.149 supports local STDIO processes and Streamable HTTP endpoints, environment-backed authentication, tool allow/deny lists, startup/tool timeouts, and server/tool approval policy. See the official Codex MCP documentation and configuration reference.

Operator registry

Place registry fragments under:

~/.config/codex-mmo/tool-mcp.d/*.toml

Fragments load in lexical filename order. When multiple fragments define the same server ID, the later definition replaces the complete earlier entry. Fields are not recursively retained across a transport change.

This example is illustrative; use the command, URL, and exact tool names documented by the MCP server you install:

schema_version = 8

[tool_mcp_servers.firecrawl]
transport = "streamable_http"
url = "https://mcp.example.invalid/"
bearer_token_env_var = "FIRECRAWL_API_KEY"
enabled_tools = ["search", "scrape"]
default_tools_approval_mode = "writes"
startup_timeout_sec = 15
tool_timeout_sec = 120

[tool_mcp_servers.firecrawl.tools.scrape]
approval_mode = "prompt"

[tool_mcp_servers.ida_pro]
transport = "stdio"
command = "ida-pro-mcp"
args = []
env_vars = ["IDA_MCP_TOKEN"]
enabled_tools = ["list_functions", "decompile"]
default_tools_approval_mode = "writes"

Every definition requires:

• A stable lowercase server ID other than mmo_mesh.
• transport = "stdio" plus command, or transport = "streamable_http" plus url.
• A non-empty enabled_tools array. This is the operator's maximum exposure, including for future profile grants.
• An explicit default_tools_approval_mode: auto, prompt, writes, or approve.

The STDIO command may be a bare executable resolved through PATH or an absolute/tilde-expanded path. STDIO definitions may also use args, absolute/tilde-expanded cwd, non-secret literal env, and environment-forwarded env_vars. HTTP definitions may use bearer_token_env_var, non-secret http_headers, and environment-backed env_http_headers. Both transports accept startup_timeout_sec, tool_timeout_sec, supports_parallel_tool_calls, and per-tool approval overrides under tools.

The private app-server lifecycle wait is automatically at least 30 seconds longer than the largest enabled startup_timeout_sec for that role, and never less than twenty minutes. A valid long MCP startup therefore is not cut off by an unrelated fixed thread-start timeout. The separate tool_timeout_sec continues to bound each Tool MCP call; it is not a model-turn deadline. The generated mmo_mesh timeout is independently derived from the largest app-server lifecycle reachable through that caller's exact spawn/control grants, plus protocol overhead.

Schema version 8 rejects OAuth fields, plaintext bearer tokens, recognizable credential-bearing literal environment/header fields, transport-incompatible fields, and unknown fields. OAuth is not copied from the base Codex home because .credentials.json can contain credentials for unrelated MCP servers.

Credentials

Put values in the existing operator credential file or the launch environment:

${EDITOR:-vi} ~/.config/codex-mmo/credentials.env

FIRECRAWL_API_KEY=replace-me
IDA_MCP_TOKEN=replace-me

Snapshots and generated TOML contain only environment variable names. At session launch, the runtime forwards only names referenced by a server selected for that Codex process. Missing values are reported by tool-mcp validate and profile doctor; a profile's required policy determines whether Codex treats server startup failure as fatal.

Profile grants

Grant servers independently to each role:

[agents.researcher.tool_mcp_servers.firecrawl]
required = true
enabled_tools = ["search"]

[agents.reverse_engineer.tool_mcp_servers.ida_pro]
required = true

required defaults to true. Omitting enabled_tools grants the complete operator allowlist; otherwise it must be a non-empty subset. A profile cannot change the command, URL, credentials, headers, timeouts, parallel-call declaration, or approval policy. Omitting a server grant disables that server for the role.

The compiler stores normalized definitions and grants in the immutable snapshot. Changing a registry definition therefore changes future snapshot identity without changing a running session.

Native-role behavior

Native roles share their parent's Codex process, and Codex recursively merges custom-agent config layers. The generated root config consequently contains the union of servers used by the root and reachable native roles. Each role layer explicitly enables its grants and disables every other server. The operator enabled_tools list remains constant, while role-specific narrowing is emitted as disabled_tools; this lets a child clear a narrower inherited deny-list without exceeding the operator maximum.

Tool visibility remains role-scoped, but process environment variables do not. If a native role uses an environment-authenticated MCP, its parent and sibling native agents share the containing process environment. Use a separately launched Agent-MCP participant when strict credential isolation is required.

Security boundary

Codex shell settings do not constrain an external MCP server:

• permissions = "read-only" controls the Codex filesystem sandbox, not whether an MCP tool can mutate an IDA database, browser, SaaS account, or other external state.
• network_access = false controls sandboxed shell networking, not an HTTP MCP connection or a local MCP process's own networking.
• MCP server instructions and tool results are external content and may carry prompt injection.

Use narrow operator allowlists, conservative approval modes, per-tool prompt overrides for mutating operations, role-specific grants, and independent verification of consequential results.

Inspection and diagnostics

These commands validate configuration without launching an MCP server:

codex-mmo tool-mcp list
codex-mmo tool-mcp show firecrawl
codex-mmo tool-mcp validate
codex-mmo tool-mcp validate firecrawl
codex-mmo profile show PROFILE --resolved
codex-mmo profile doctor PROFILE

Readiness checks report command resolution, working-directory availability, and whether referenced environment variables are present. They never print credential values. Actual protocol/tool behavior remains a live acceptance concern; exercise it through a profile smoke task after reviewing the server and its tool schema.