---
title: Do AI Agents Read MCP Server Instructions? Tested in 5 Apps
description: MCP server instructions reached the model in all 5 agent apps we captured, but Claude Code cut them at 4,096 characters, Grok at ~2,048, and Codex moved them.
canonical: https://spiritroom.app/blog/do-agents-read-mcp-server-instructions/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/do-agents-read-mcp-server-instructions/ for agents. Index: /llms.txt

[Blog](/blog/) / [Onboard agents through MCP](/guides/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

**TL;DR**

- **Yes, all five apps passed instructions to the model** (Claude Code 2.1.301, Codex 0.161, Grok Build 1.0.60, OpenCode 1.18.34 and 2.0.31, captured 16 Oct 2026).
- **Claude Code cuts them at 4,096 characters** and puts them in the system prompt.
- **Grok Build cuts them at about 2,048 characters** and sends them as a reminder at session start. In 1 of 2 runs they arrived too late to be used.
- **Codex doesn't put them in the first prompt.** It puts them in front of every tool description, so the model sees them only after it searches your tools.
- **Agents do act on them.** A one-line hint in the instructions got a start-here tool called first in 12 of 12 runs each in Claude Code and Codex (mock).
- **Rule of thumb:** under 2,000 characters, most important line first, and repeat anything critical where it can't be cut.
[The short answer](#short-answer)[Where instructions land, per app](#per-app)[What gets cut](#cut)[Do agents act on them?](#act)[How to write instructions that survive](#write)[How we measured](#how-we-measured)[FAQ](#faq)

## 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

Server instructions on the wire, 16 Oct 2026

| Agent app | Where the model sees them | How much |
| --- | --- | --- |
| Claude Code 2.1.301 | System prompt, from the first request | **First 4,096 characters** |
| Codex 0.161 (code mode) | In front of **every tool description** of the server, seen after the model searches the tools; not in the first request | Full |
| Grok Build 1.0.60 | A reminder at session start; in 1 of 2 runs it arrived too late | **About 2,048 characters**, then “[truncated]” |
| OpenCode 1.18.34 | System prompt | Full |
| OpenCode 2.0.31 | After the tool catalog | Full |

Grok Build

*~2,048 chars*

Claude Code

*4,096 chars*

Codex, OpenCode 1 and 2

*full text*

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](https://github.com/openai/codex/issues/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](/blog/mcp-server-instructions-length/).

**Find where agents fail on your tools. Measure what fixes it.**

Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes.

[Test your MCP →](/#contact)

## 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.”

Called the start-here tool first, job requests, mock server, 18 Oct 2026

| Setup | Claude Code | Codex |
| --- | --- | --- |
| Tool only, no hint | 1/24 (1–20%) | 9/24 (21–57%) |
| Hint at the start of the instructions | 12/12 (76–100%) | 12/12 (76–100%) |

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](/blog/get-instructions-first-24-of-24/).

## 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](/blog/mcp-prompts-resources-tools-which-agents-use/).
6. **Test in the apps your users run.** Cutoffs and placement change with versions. See [how to test an MCP server with real agents](/guides/test-mcp-servers-with-agents/).

**Go deeper:** [Onboard agents through your MCP server](/guides/onboard-agents-through-mcp/), [Agent skills vs an MCP server](/blog/agent-skills-vs-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](https://github.com/anthropics/claude-code/issues/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](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/), MCP blog.
- [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli): server instructions and the first 512 characters.
- [anthropics/claude-code #3312](https://github.com/anthropics/claude-code/issues/3312): instructions added to Claude Code's system prompt.
- [openai/codex #29097](https://github.com/openai/codex/issues/29097): instructions routed to tool namespace metadata.

## FAQ

### Does Claude Code read MCP server instructions?

Yes. In our capture of Claude Code 2.1.301 the instructions went into the system prompt, cut at 4,096 characters. Anything after that point never reached the model.

### Does Codex use MCP server instructions?

Yes, but not as a system-prompt block. Codex 0.161 put the instructions in front of every one of the server's tool descriptions, so the model only saw them once it searched the server's tools. On a vague request where it never searched, the model never saw them.

### Is there a length limit for MCP server instructions?

The spec sets none, but apps do. We measured 4,096 characters in Claude Code and about 2,048 in Grok Build; OpenCode passed the full text. Codex's own docs recommend keeping the first 512 characters self-contained.

### Should I repeat my instructions in tool descriptions?

Repeat the one or two lines that must never be missed, not the whole text. A single line at the start of each tool description, such as pointing to a start-here tool, fixed the Grok run where instructions arrived too late, and costs about 12 tokens per tool.

### Do MCP server instructions work in Claude Desktop, Cursor or VS Code?

We haven't captured those apps yet. Public reports say Claude Desktop has dropped instructions. Test the app your users run before relying on them.

**Find where agents fail on your tools. Measure what fixes it.**

Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes.

[Test your MCP →](/#contact)

## Keep reading

- Up[How to onboard AI agents through your MCP server (guide)](/guides/onboard-agents-through-mcp/)
- Related[How long should MCP server instructions be? Why 115,000 characters reached the model as 2,067](/blog/mcp-server-instructions-length/)
- Related[MCP prompts vs resources vs tools: which ones agents actually see (tested in 5 agent apps)](/blog/mcp-prompts-resources-tools-which-agents-use/)
- Related[Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex](/blog/get-instructions-first-24-of-24/)