Codex cancels context-mode MCP tool calls because ctx_* descriptors lack annotations

[ken-jo]

Summary

Context-mode MCP tools currently register without MCP tool annotations. In Codex, this causes read-only context-mode MCP calls such as ctx_stats and ctx_doctor to be cancelled before execution with user cancelled MCP tool call, even though the MCP server itself is reachable and the same tools work through direct MCP protocol probes.

This appears to be a descriptor/approval metadata gap, not a broken MCP server.

Observed behavior

Validated on Linux with codex-cli 0.139.0:

• Direct MCP JSONL probes against context-mode returned the full tool list and ctx_stats executed successfully.
• Claude Code could invoke the context-mode MCP tool successfully.
• Codex could invoke other MCP servers in the same environment, including openaiDeveloperDocs.list_api_endpoints and omg.notepad_stats.
• Codex exec attempted context-mode.ctx_stats / ctx_doctor, but the MCP tool call completed with:

user cancelled MCP tool call

A minimal MCP probe reproduced the same pattern: an unannotated test MCP tool was cancelled by Codex, while the same tool with annotations such as readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: false was allowed.

Git archaeology

History check did not find a prior annotations implementation:

git log --all --oneline -S 'readOnlyHint' -- src tests hooks package.json

No matching commits were found. This looks like a validation gap rather than a regression that removed existing annotations.

Relevant current code:

• src/server.ts wraps server.registerTool() and records tool configs, but forwards the config as-is.
• Tool registrations such as ctx_stats and ctx_doctor provide title, description, and inputSchema, but no annotations.
• tests/core/server.test.ts has a tool-description style contract that recognizes annotations as a possible block delimiter, but does not require annotations or verify read-only/destructive metadata.

Expected behavior

Context-mode should provide correct MCP tool annotations so MCP clients with approval/permission logic can distinguish read-only diagnostic/search tools from mutating or open-world tools.

At minimum, read-only tools such as ctx_stats, ctx_doctor, and other truly read-only query/diagnostic tools should carry accurate annotations. Mutating, destructive, process-spawning, or open-world tools should not be incorrectly marked read-only.

Actual behavior

Context-mode exposes ctx_* tools without annotations. Codex treats unannotated context-mode tools conservatively and cancels calls that should be safe/read-only.

Suggested fix direction

• Add explicit, accurate MCP annotations to each registered ctx_* tool.
• Add regression coverage that inspects the actual registered tool descriptors, not only descriptions.
• Avoid blanket readOnlyHint: true; classify each tool by real behavior.