Files

T

retoor 251c3dc2ba research: mcp-client-support subject (106 sources, 3 conclusions)

- wire spec: lifecycle, stdio + Streamable HTTP transports, tools,
  utilities, legacy SSE, versioning, changelog (14 Tier 1)
- client ecosystem: Claude Code/VS Code/Cursor/Codex configs,
  mcp-remote, Smithery, registries, Glama (12 Tier 1)
- security/ops: authorization draft, trust model, poisoning,
  rug pulls, production hardening (12 Tier 1) + 68 Tier 2 cards
- conclusions: minimal stdlib client on 2025-11-25, normalizer +
  resolver agent for pasted configs/GitHub URLs, untrusted-until-
  consent trust model; nothing built yet
- audit PASS (14 subjects, 797 sources, 32 conclusions)

2026-10-18 19:23:02 +02:00

3.6 KiB

Raw Blame History

Codex MCP docs (learn.chatgpt.com, official OpenAI Codex docs)

Metadata

Field	Value
Institute	Molodetz Institute - Research and Retrieval Division
Subject	mcp-client-support
Document type	Source Dossier
Tier	1
Source title	Codex MCP docs
Source URL	https://learn.chatgpt.com/docs/extend/mcp
Source publisher / author	OpenAI
Source type	vendor docs
Source date (published)	Unknown, not stated
Date researched	2026-10-18
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	gather-subagent direct page fetch, parent synthesis from evidence pack
Confidence	High
Status	Active

Summary

Official OpenAI documentation for MCP configuration in Codex. It is the TOML counterpart to the JSON config dialects: servers live in config.toml under [mcp_servers.<server-name>] tables, with distinct stdio fields (command, env, env_vars, cwd) and HTTP fields (url, auth, bearer_token_env_var, http_headers, env_http_headers, http_headers_helper), plus per-server policy (enabled, tool allow/deny lists, timeouts) and CLI parity through codex mcp.

Key findings

"Codex stores MCP configuration in config.toml... By default this is ~/.codex/config.toml, but you can also scope MCP servers to a project with .codex/config.toml (trusted projects only)" and "Configure each MCP server with a [mcp_servers.<server-name>] table".
STDIO fields: command (required), args, env, env_vars ("Environment variables to allow and forward", e.g. env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]), cwd.
HTTP fields: url (required), auth (oauth default / chatgpt), bearer_token_env_var ("Environment variable name for a Bearer [REDACTED]"), http_headers (static map), env_http_headers (header-to-env-var-name map), http_headers_helper (command printing a JSON header object; refreshed once after 401/403 "only if the helper returns changed values").
Per-server policy in TOML: enabled = false ("disable a server without deleting it"), enabled_tools allow list, disabled_tools "deny list (applied after enabled_tools)", startup_timeout_sec (default 10), tool_timeout_sec (default 60), approval modes.
CLI parity: codex mcp add <name> --env K=V ... -- <cmd>, codex mcp list, codex mcp login <server-name> for OAuth; "The ChatGPT desktop app, Codex CLI, and IDE extension share this configuration."

Pros / strengths

First-party statement of the only TOML-shaped client schema in the set, so Codex output rules derived from it are authoritative.
The header-auth ladder (static map, env-var map, helper command) covers static, secret, and dynamic credentials with exact refresh semantics.
Shared configuration across desktop app, CLI, and IDE extension means one resolved form serves all three surfaces.

Cons / limitations / caveats

No publish date; TOML field details could drift without notice.
The near-empty-env claim (Codex starts servers with a near-empty environment, hence explicit env_vars forwarding) comes from third-party notes only and is unconfirmed from this page alone.
Documents Codex conventions only; the TOML schema shares almost no surface with the JSON dialects.

Relevance to tai

The TOML counterpart schema: resolver output for Codex users must be [mcp_servers.<name>] tables with env_vars/env_http_headers instead of JSON env/headers. Required for any Codex-targeted resolution path.

Changelog

Date	Change
2026-10-18	Initial dossier created.

3.6 KiB Raw Blame History