169 lines
7.1 KiB
Markdown
169 lines
7.1 KiB
Markdown
# 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](https://developers.openai.com/codex/mcp) and
|
|
[configuration reference](https://developers.openai.com/codex/config-reference).
|
|
|
|
## Operator registry
|
|
|
|
Place registry fragments under:
|
|
|
|
```text
|
|
~/.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:
|
|
|
|
```toml
|
|
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:
|
|
|
|
```bash
|
|
${EDITOR:-vi} ~/.config/codex-mmo/credentials.env
|
|
```
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```bash
|
|
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.
|