Blog / Onboard agents through MCP

Do AI agents read your MCP server instructions? Tested in Claude Code, Codex, Grok and OpenCode

The MCP spec gives your server one field to brief every agent: instructions. Whether the model reads it depends on the app. We captured what five agent app versions actually sent to their models. All five passed the instructions on, but one cut them at about 2,000 characters, another at 4,096, and Codex moved them somewhere else entirely.

Leonid Bugaev · Published 21 Oct 2026

The short answer

Yes, the agent apps we tested read your MCP server instructions. But “read” hides three different behaviours: the text gets cut, moved or delayed, depending on the app. The spec leaves this open (clients may add instructions to the system prompt), and the official advice is to test each client. So we did.

We connected a test server whose instructions began with a unique marker word to five agent app versions, captured every model request, and checked where the marker showed up and how much text came with it.

Where instructions land, per app

The Codex behaviour matches what others found in its source code: the instructions become the description of the server's tool namespace, not instruction-level guidance (openai/codex #29097). We saw the effect in our runs: on a vague request, Codex sometimes never searched the tools, so the model never saw the instructions or any hint in them.

What gets cut, in practice

Two production servers we looked at sent far more than the cutoffs:

• A 99-tool server sent 5,092 characters. Claude Code dropped about 1,000 of them and Grok Build about 3,000.
• Another server sent 115,077 characters (26,633 tokens): a full playbook. Grok Build passed the model the first 2,067 characters and “[truncated]”. The rule that mattered most, “always call the status tool first on every connection”, sat at character 28,484. The model never saw it. Claude Code's 4,096-character cut would have missed it too.

The second text opened with a work standard and a trust statement; the operational rule came more than 26,000 characters later. Put that rule first. More on length in how long MCP server instructions should be (coming soon).

Do agents act on them?

Reaching the model is one thing; changing what it does is another. On a mock of the 99-tool server we added a get_instructions tool and tested a one-line hint at the start of the instructions, along the lines of “Before doing anything, call get_instructions with the job you are doing.”

So instructions that survive the cut work, in both apps. In Grok Build the hint in the instructions worked in 1 of 2 runs; the miss was the run where the instructions arrived late. A line in every tool description fixed it (2 of 2). The full recipe is in make the agent read your playbook first.

How to write instructions that survive

1. Put the most important line first. Codex's docs recommend keeping the first 512 characters self-contained; that's a good target for the rule that must never be missed.
2. Stay under 2,000 characters in total, so Grok Build and Claude Code see all of it.
3. Point to a tool for the rest. Long playbooks belong in a start-here tool that returns the right one per job, not in the instructions.
4. Repeat only what's critical, as one line at the start of each tool description. It survives Codex's placement and Grok's late arrival.
5. Don't rely on prompts or resources to carry instructions: prompts reached the model in none of the five apps. See which MCP channels agents actually see.
6. Test in the apps your users run. Cutoffs and placement change with versions. See how to test an MCP server with real agents.

Go deeper: Onboard agents through your MCP server.

How we measured

• Capture: a local stub serving a production server's recorded 99-tool list, with a unique marker word at the start of the instructions and another at the end of a long version. Model traffic was recorded through a temporary intercepting proxy scoped to the agent's process; we searched every model request for the markers and measured the text around them.
• Apps: Claude Code 2.1.301, Codex 0.161, Grok Build 1.0.60, OpenCode 1.18.34 and OpenCode 2.0.31, on 16 Oct 2026. The 115,077-character case was a separate Grok Build capture on 17 Oct 2026.
• Behaviour: the 12/12 and 1/24, 9/24 rows come from 232 mock runs on 18 Oct 2026 (Claude Code 2.1.302, Codex 0.161.0). Grok rows are 2 runs each, which shows direction, not a rate.
• Not tested: Claude Desktop, Cursor, VS Code. Public reports say Claude Desktop has dropped instructions (anthropics/claude-code #23808).

Sources

• Spirit Room wire captures, 16–17 Oct 2026, and mock runs, 18 Oct 2026.
• Server instructions: giving LLMs a user manual for your server, MCP blog.
• Codex MCP documentation: server instructions and the first 512 characters.
• anthropics/claude-code #3312: instructions added to Claude Code's system prompt.
• openai/codex #29097: instructions routed to tool namespace metadata.