Blog / Onboard agents through MCP
How long should MCP server instructions be? Why 115,000 characters reached the model as 2,067
The instructions field is the one place an MCP server can tell every agent how to behave. It's tempting to put the whole manual there. But the apps your users run don't pass all of it to the model, and the part they drop is the end. Here is where the cuts are, what two real servers lost, and a budget that works.
Limits by app
The MCP spec lets a server return free-text instructions when a client connects, with no length limit. What reaches the model is up to the app. We captured it on the wire:
| App (version) | Where instructions go | Length passed |
|---|---|---|
| Claude Code 2.1.301 | System prompt | First 4,096 characters |
| Grok Build 1.0.60 | Reminder at session start | About the first 2,048 characters |
| Codex 0.161 | Attached to the server's tools, not the first prompt | Seen only after the model searches the tools |
| OpenCode 1.18.34 | System prompt | Full |
| OpenCode 2.0.31 | After the tool catalog | Full |
Where each app puts them, and whether agents follow them: do agents read MCP server instructions?
What two real servers lost
5,092 characters: the end goes missing
A 99-tool production server sent 5,092 characters of instructions, about 1,100 tokens. Claude Code dropped about the last 1,000 characters and Grok Build about the last 3,000. Neither told the server.
115,077 characters: the key rule never arrives
Another production server we looked at sent 115,077 characters, 2,077 lines, 26,633 tokens, as instructions. Its most important rule, “call the status tool first”, first appeared at character 28,484. Grok Build passed the model the first 2,067 characters, ending in “… [truncated]”. The model saw a work standard and the start of one paragraph, and nothing about where to begin.
What saved it: the same rule was repeated in tool descriptions, above all the start tool's own. In our runs, that is what got the agent to the right first call.
Check what your instructions look like to each agent.
We capture what Claude Code, Codex, Grok, OpenCode and the other apps your users run actually pass to the model, and test whether agents follow it.
A short text that worked
On a mock of the 99-tool server, we replaced the 5,092-character instructions with 728 characters that opened with one rule: before anything else, call get_instructions with the job you're doing.
| Setup | Claude Code calls it first | Codex calls it first |
|---|---|---|
| Start-here tool, original instructions | 1/24 (1–20%) | 9/24 (21–57%) |
| Same tool, 728-character instructions with the hint | 12/12 (76–100%) | 12/12 (76–100%) |
Short instructions with the rule first were enough for both apps in this test. The full recipe, which adds a one-line hint to every tool description, reached 24 of 24 in each: make agents read your playbook first.
Go deeper: Why agents don't use your MCP server, Skills vs MCP instructions, Prompts, resources or tools?.
How to write within the budget
- Under about 2,000 characters. That survives the smallest cut we measured.
- The must-not-miss rule first, in one sentence: where to start, and what never to do without asking.
- The long method behind a tool, for example
get_instructions(job), returning only the playbook for the current job. - Repeat the start rule in tool descriptions, first line, so apps that never show the instructions still carry it.
- Check per app: capture what each app passes to the model, because limits change between versions.
More: onboard agents through your MCP server.
How we measured
- Captures: a local stub server with the 99 recorded tools and unique marker words in each channel, real model calls, traffic captured through a temporary process-scoped proxy, 16 Oct 2026.
- 115k server: instructions from Grok Build's own debug log of the connection handshake; what reached the model from its session reminder; read-only, nothing saved.
- Short text: 232 mock runs, Claude Code and Codex, 18 Oct 2026; ranges are 95% Wilson intervals.
- Limits: versions as listed; characters, not tokens, are what the cuts count.
FAQ
Is there a length limit for MCP server instructions?
Not in the MCP spec. But agent apps cut them: in our captures Claude Code 2.1.301 kept the first 4,096 characters and Grok Build 1.0.60 about 2,048. OpenCode passed them in full. Codex attached them to the server's tools rather than the system prompt.
How long should MCP server instructions be?
Under about 2,000 characters, so they survive the smallest cut we found, with the most important rule in the first sentence. Ours was 728 characters, about 170 tokens.
What happens to instructions longer than the limit?
The end is dropped, with no error to the server. A 115,077-character text reached the model in Grok Build as its first 2,067 characters, so a rule at character 28,484 was never seen.
Where should the long documentation go?
Behind a tool such as get_instructions(job) that returns the playbook for the job at hand, plus one line at the top of each tool description pointing to it.
Check what your instructions look like to each agent.
We capture what Claude Code, Codex, Grok, OpenCode and the other apps your users run actually pass to the model, and test whether agents follow it.