Bundled `openai-docs` skill instructs agents to use Docs MCP even though it is not configured by default
Open 💬 5 comments Opened May 23, 2026 by alexchexes
What version of Codex CLI is running?
codex-cli 0.132.0
What subscription do you have?
plus
Which model were you using?
gpt-5.5
What platform is your computer?
Microsoft Windows NT 10.0.26100.0 x64
What terminal emulator and version are you using (if applicable)?
PowerShell / Git-Bash / VS Code Codex extension
Codex doctor report
{
"schemaVersion": 1,
"generatedAt": "1779550644s since unix epoch",
"overallStatus": "ok",
"codexVersion": "0.132.0",
"checks": {
"app_server.status": {
"id": "app_server.status",
"category": "app-server",
"status": "ok",
"summary": "background server is not running",
"details": {
"control socket": "C:\\Users\\Alex\\.codex\\app-server-control\\app-server-control.sock",
"daemon state dir": "C:\\Users\\Alex\\.codex\\app-server-daemon",
"mode": "ephemeral",
"pid file": "C:\\Users\\Alex\\.codex\\app-server-daemon\\app-server.pid (missing)",
"settings": "C:\\Users\\Alex\\.codex\\app-server-daemon\\settings.json (missing)",
"status": "not running",
"update-loop pid file": "C:\\Users\\Alex\\.codex\\app-server-daemon\\app-server-updater.pid (missing)"
},
"remediation": null,
"durationMs": 0
},
"auth.credentials": {
"id": "auth.credentials",
"category": "auth",
"status": "ok",
"summary": "auth is configured",
"details": {
"auth file": "C:\\Users\\Alex\\.codex\\auth.json",
"auth storage mode": "File",
"stored API key": "false",
"stored ChatGPT tokens": "true",
"stored agent identity": "false",
"stored auth mode": "chatgpt"
},
"remediation": null,
"durationMs": 0
},
"config.load": {
"id": "config.load",
"category": "config",
"status": "ok",
"summary": "config loaded",
"details": {
"CODEX_HOME": "C:\\Users\\Alex\\.codex",
"config.toml": "C:\\Users\\Alex\\.codex\\config.toml",
"config.toml parse": "ok",
"cwd": "C:\\WINDOWS\\system32",
"enabled feature flags": "shell_tool, shell_snapshot, terminal_resize_reflow, sqlite, hooks, enable_request_compression, multi_agent, apps, tool_search, tool_suggest, plugins, plugin_hooks, in_app_browser, browser_use, browser_use_external, computer_use, plugin_sharing, image_generation, skill_mcp_dependency_install, steer, guardian_approval, collaboration_modes, tool_call_mcp_elicitation, personality, fast_mode, tui_app_server, workspace_dependencies",
"feature flag overrides": "none",
"feature flags enabled": "27",
"log dir": "C:\\Users\\Alex\\.codex\\log",
"mcp servers": "3",
"model": "gpt-5.5",
"model provider": "openai",
"sqlite home": "C:\\Users\\Alex\\.codex"
},
"remediation": null,
"durationMs": 0
},
"installation": {
"id": "installation",
"category": "install",
"status": "ok",
"summary": "installation looks consistent",
"details": {
"PATH codex #1": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\codex",
"PATH codex #2": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\codex.cmd",
"PATH codex entries": "2",
"current executable": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex\\node_modules\\@openai\\codex-win32-x64\\vendor\\x86_64-pc-windows-msvc\\codex\\codex.exe",
"install context": "npm",
"managed by bun": "false",
"managed by npm": "true",
"managed package root": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex",
"npm update target": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex"
},
"remediation": null,
"durationMs": 260
},
"mcp.config": {
"id": "mcp.config",
"category": "mcp",
"status": "ok",
"summary": "MCP configuration is locally consistent",
"details": {
"configured servers": "3",
"disabled servers": "0",
"stdio servers": "3"
},
"remediation": null,
"durationMs": 8
},
"network.env": {
"id": "network.env",
"category": "network",
"status": "ok",
"summary": "network-related environment looks readable",
"details": {
"proxy env vars": "none"
},
"remediation": null,
"durationMs": 0
},
"network.provider_reachability": {
"id": "network.provider_reachability",
"category": "reachability",
"status": "ok",
"summary": "active provider endpoints are reachable over HTTP",
"details": {
"ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 403)",
"reachability mode": "ChatGPT auth"
},
"remediation": null,
"durationMs": 134
},
"network.websocket_reachability": {
"id": "network.websocket_reachability",
"category": "websocket",
"status": "ok",
"summary": "Responses WebSocket handshake succeeded",
"details": {
"DNS": "2 IPv4, 0 IPv6, first IPv4",
"auth mode": "chatgpt",
"connect timeout": "15000 ms",
"endpoint": "wss://chatgpt.com/backend-api/<redacted>",
"handshake result": "HTTP 101 Switching Protocols",
"model provider": "openai",
"models etag present": "true",
"provider name": "OpenAI",
"proxy env vars": "none",
"reasoning header": "false",
"server model present": "false",
"supports websockets": "true",
"wire API": "responses"
},
"remediation": null,
"durationMs": 527
},
"runtime.provenance": {
"id": "runtime.provenance",
"category": "runtime",
"status": "ok",
"summary": "running npm on windows-x86_64",
"details": {
"commit": "unknown",
"current executable": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex\\node_modules\\@openai\\codex-win32-x64\\vendor\\x86_64-pc-windows-msvc\\codex\\codex.exe",
"install method": "npm",
"platform": "windows-x86_64",
"version": "0.132.0"
},
"remediation": null,
"durationMs": 0
},
"runtime.search": {
"id": "runtime.search",
"category": "search",
"status": "ok",
"summary": "search is OK (system)",
"details": {
"search command": "rg.exe",
"search command readiness": "ripgrep 15.1.0 (rev af60c2de9d)",
"search provider": "system"
},
"remediation": null,
"durationMs": 153
},
"sandbox.helpers": {
"id": "sandbox.helpers",
"category": "sandbox",
"status": "ok",
"summary": "sandbox configuration is readable",
"details": {
"approval policy": "OnRequest",
"codex-linux-sandbox helper": "none",
"execve wrapper helper": "none",
"filesystem sandbox": "restricted",
"network sandbox": "restricted"
},
"remediation": null,
"durationMs": 0
},
"state.paths": {
"id": "state.paths",
"category": "state",
"status": "ok",
"summary": "state paths and databases are inspectable",
"details": {
"CODEX_HOME": "C:\\Users\\Alex\\.codex (dir)",
"active rollout files": "208 files, 1244767525 total bytes, 5984459 average bytes",
"archived rollout files": "0 files, 0 total bytes, 0 average bytes",
"log DB": "C:\\Users\\Alex\\.codex\\logs_2.sqlite (file)",
"log DB integrity": "ok",
"log dir": "C:\\Users\\Alex\\.codex\\log (dir)",
"sqlite home": "C:\\Users\\Alex\\.codex (dir)",
"state DB": "C:\\Users\\Alex\\.codex\\state_5.sqlite (file)",
"state DB integrity": "ok"
},
"remediation": null,
"durationMs": 477
},
"terminal.env": {
"id": "terminal.env",
"category": "terminal",
"status": "ok",
"summary": "terminal metadata was detected",
"details": {
"DISPLAY": "present",
"WT_SESSION": "present",
"color output": "enabled",
"effective locale": "en_US.UTF-8",
"stderr is terminal": "true",
"stdin is terminal": "true",
"stdout is terminal": "true",
"terminal": "Windows Terminal",
"terminal size": "120x35"
},
"remediation": null,
"durationMs": 0
},
"updates.status": {
"id": "updates.status",
"category": "updates",
"status": "ok",
"summary": "update configuration is locally consistent",
"details": {
"cached latest version": "0.133.0",
"check for update on startup": "true",
"last checked at": "2026-05-21T21:43:36.389844600Z",
"latest version": "0.133.0",
"latest version status": "newer version is available",
"npm update target": "C:\\Users\\Alex\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex",
"update action": "npm install -g @openai/codex",
"version cache": "C:\\Users\\Alex\\.codex\\version.json"
},
"remediation": null,
"durationMs": 628
}
}
}What issue are you seeing?
The bundled official openai-docs skill tells the agent to prioritize the OpenAI Developer Docs MCP tools:
mcp__openaiDeveloperDocs__search_openai_docsmcp__openaiDeveloperDocs__fetch_openai_docmcp__openaiDeveloperDocs__list_openai_docs
However, a default/local Codex setup may not have openaiDeveloperDocs configured, so those tools are not available in the thread. The agent then reports that the OpenAI Docs MCP is unavailable and falls back to web search.
This is confusing because the skill is bundled/official and reads as if the matching MCP is part of the normal available tool surface. The Docs MCP is optional setup, but the skill does not make that clear at point of use.
What steps can reproduce the bug?
- Use a Codex setup where
openaiDeveloperDocsis not configured. - Verify:
``sh`
codex mcp list
In my case, the list contains other MCP servers but not
- Ask Codex a question that triggers the bundled
openai-docsskill, for example:
``text``
Research current Codex docs for /goal and code review behavior.
- Observe output like
```
<Ran command>
$ Get-Content -Path C:\Users\Alex\.codex\skills\.system\openai-docs\SKILL.md
...
<Codex thinking>
The OpenAI docs MCP tool is not available in this session, so I’m using official OpenAI web sources as the fallback
``
because that skill tells Codex to use
What is the expected behavior?
One of these should happen:
- Codex should bundle/configure the OpenAI Developer Docs MCP by default when the official
openai-docsskill is bundled, or - the bundled skill should clearly treat Docs MCP as optional and instruct the agent to check availability first, or
- Codex should surface a clearer setup hint when a bundled skill references an unavailable first-party MCP.
Actual behavior:
The official bundled skill strongly instructs the agent to use an MCP server that is not necessarily configured or exposed in the current session. This creates a confusing mismatch between bundled skill instructions and actual available tools.
Additional information
The official setup command works as the likely workaround:
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcpBut users may not know they need to run this, because the openai-docs skill is already bundled and appears official.
This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗