Repository navigation
Bundled openai-docs skill instructs agents to use Docs MCP even though it is not configured by default #24239
Description
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:
In my case, the list contains other MCP servers but not
codex mcp list
openaiDeveloperDocs. - Ask Codex a question that triggers the bundled
openai-docsskill, for example:Research current Codex docs for /goal and code review behavior. - Observe output like
because that skill tells Codex to use
<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 fallbackmcp__openaiDeveloperDocs__...tools, but those tools are not available in the session which is the default codex Windows CLI / Extension / App setup.
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.
Activity
jshaofa-ui commentedon May 23, 2026
Proposed Solution: Stale MCP Dependency in Bundled Skill
Root Cause
Bundled
openai-docsskill references a Docs MCP server that is not available. On Windows, the MCP server may fail to start due to path/permission issues. Users cannot easily fix bundled skills.Fix
Testing
Full solution:
solutions/codex-24239-openai-docs-skill-docs-mcp-unavailable-fix.mdyui-stingray commentedon May 23, 2026
I checked current
openai/codex@7d47056; this looks like a dependency/discoverability mismatch rather than only a missing local MCP config.Two repo pointers:
codex-rs/skills/src/assets/samples/openai-docs/agents/openai.yamldeclaresopenaiDeveloperDocsas an MCP dependency withhttps://developers.openai.com/mcp.codex-rs/skills/src/assets/samples/openai-docs/SKILL.mdstarts with MCP-first instructions and only later has an “If MCP server is missing” section withcodex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp.Meanwhile the CLI/TUI also supports MCP servers being absent or manually configured (
codex mcp listcan report no configured servers, and the TUI tooltip separately tells users how to enable the OpenAI docs MCP). There is also an auto-install path behindskill_mcp_dependency_install, but that still leaves the skill text confusing in sessions where the dependency has not been installed or exposed.A narrow fix could be to make the optional dependency explicit near the top of the skill, or move the missing-MCP guidance before the MCP-only tool names, so agents do not first try unavailable
mcp__openaiDeveloperDocs__*calls.omarpinarecords commentedon May 27, 2026
Adding a related macOS Desktop data point because this appears to affect the skill MCP dependency detection path even when the server is already installed.
Environment:
Observed UI prompt:
The following MCP servers are required by the selected skills but are not installed yet: openaiDeveloperDocs. Install them now?Local state contradicts the prompt:
~/.codex/config.tomlcontains:codex mcp listreports:The MCP tool is also callable in the active session;
mcp__openaiDeveloperDocs__search_openai_docssuccessfully returned OpenAI docs results.So this is not just the bundled skill referencing an optional MCP server that is absent. At least in Desktop, the selected-skills dependency prompt can report
openaiDeveloperDocsas missing even when it is configured, enabled, and usable.Expected behavior: the dependency preflight should use the same resolved MCP/tool availability state that the agent session uses, or suppress the install prompt when the server is already configured and callable. If the app is checking a different registry/scope than
codex mcp listand the active tool surface, the prompt should say that explicitly instead of asking to reinstall an already-working first-party MCP server.omarpinarecords commentedon May 27, 2026
One clarification on the macOS Desktop data point above: this is not a request to use Chronicle-off as a workaround.
On this machine Chronicle is intentionally enabled:
There is a separate Chronicle / macOS ScreenCaptureKit performance issue tracked in #20313, but the false
openaiDeveloperDocsmissing-dependency prompt should be handled independently. Disabling Chronicle may hide or change some app behavior, but it is not an acceptable fix for this selected-skills dependency prompt when the Docs MCP server is already configured, enabled, and callable.GabrielSotto commentedon Jul 10, 2026
This still reproduces in the post-rebrand Windows desktop app.
Environment:
OpenAI.Codex_26.707.3748.0_x64__2p2nqsd0c76g0The bundled
openai-docsskill and itsagents/openai.yamlwere installed/updated together on 2026-07-10. The YAML declaresopenaiDeveloperDocsas an MCP dependency, but that MCP was not exposed to the agent and was absent fromconfig.toml.The skill then instructed the agent to run:
That recovery also failed in the desktop environment because the packaged executable under
C:\Program Files\WindowsApps\OpenAI.Codex_26.707.3748.0_x64__2p2nqsd0c76g0\app\resources\codex.execould not be launched from PowerShell:Access denied.User-visible impact: three separate questions about current Codex behavior caused the agent to announce that the official docs source was unavailable and fall back to web search. This did not happen before the July 9 desktop app rebrand/update.
This looks like an unresolved dependency auto-install/exposure regression in the Windows desktop app, plus a broken self-recovery path for the packaged CLI.