MCP server instructions are not reliably exposed as server-wide agent guidance

Summary

Codex documents support for MCP server instructions:

Codex reads the MCP instructions field returned during initialization and uses it as server-wide guidance alongside the server's tools.

In practice, MCP InitializeResult.instructions do not appear to be exposed to the model as instruction-level, server-wide guidance. They are not visible to the agent as a distinct instruction block, cannot be reliably recalled by the agent, and do not reliably affect behavior for MCP servers whose value depends on cross-tool usage policy.

This is especially painful for MCP servers such as code navigation or memory systems, where the important guidance is not tied to one tool schema but to when to use the server at all.

Why this matters

Some MCP servers need server-wide behavioral guidance, for example:

• use structural code navigation before grep for definition/caller/type-hierarchy questions
• use memory recall before asserting prior context is unavailable
• distinguish "no results" from "index not ready" using server-wide readiness metadata
• prefer semantic reference/caller queries over text search for specific classes of questions

Those are cross-tool policies. Duplicating them into every tool description is brittle and bloats tool schemas. tools/list result _meta is also not a viable workaround for model guidance.

Observed behavior

In a Codex Desktop session with MCP servers that return non-trivial InitializeResult.instructions, the agent could see the individual MCP tools and their tool descriptions, but when asked whether the MCP server instructions had been provided, it could not see or summarize the server-wide instruction text. It only had access to the tool-level descriptions.

After the instruction text was pasted into the conversation manually, the agent could follow it, which suggests the issue is not with the instruction content itself but with how it is ingested/exposed by Codex.

Source-level observation

From the current openai/codex implementation, Codex does read initialize_result.instructions, but it appears to route it through MCP tool namespace metadata rather than injecting it as instruction-level context.

Relevant paths:

• codex-rs/codex-mcp/src/rmcp_client.rs
• initialize_result.instructions is passed to list_tools_for_client_uncached(...)
• for ordinary MCP servers, it becomes ToolInfo.namespace_description
• codex-rs/core/src/tools/handlers/mcp.rs
• namespace_description is used as ResponsesApiNamespace.description
• it is also included in tool search text/source info

That means the data is not discarded, but it is effectively demoted from server-wide instructions to tool/namespace metadata. This does not provide the same semantics as instruction-level guidance, and it is not inspectable by the agent as "the MCP server instructions".

Expected behavior

For MCP servers that return InitializeResult.instructions, Codex should expose those instructions as reliable server-wide guidance to the model, with instruction-level priority comparable to other durable tool-use guidance.

At minimum, Codex should make the behavior explicit and inspectable:

• show which MCP server instructions were accepted for the session
• document whether they are injected as instructions, namespace descriptions, tool search metadata, or something else
• expose truncation/precedence behavior if applicable

Actual behavior

The instructions appear to be available only indirectly as MCP namespace/tool metadata. In practice, the agent cannot reliably recall them or follow them as server-wide behavior.

Reproduction sketch

1. Configure an MCP server that returns an instructions string during initialization, for example a distinctive sentinel plus a cross-tool rule such as: "For structural code questions, use this MCP server before grep."
2. Start a new Codex Desktop or CLI session with that server enabled.
3. Ask the agent what MCP server instructions it received.
4. Ask a task that should trigger the server-wide rule.

Observed: the agent sees the tools, but does not reliably see or follow the server-wide instruction text unless it is also duplicated into individual tool descriptions or the user prompt.

Related but distinct

This is not the same as MCP prompts support. It concerns the standard MCP InitializeResult.instructions field, which Codex docs already describe as server-wide guidance.