--- title: How Long Should MCP Server Instructions Be? (Measured) description: No spec limit, but Claude Code cuts MCP server instructions at 4,096 characters and Grok at ~2,048. Keep them under 2,000 with the key rule first. Measured. canonical: https://spiritroom.app/blog/mcp-server-instructions-length/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/mcp-server-instructions-length/ for agents. Index: /llms.txt [Blog](/blog/) / [Onboard agents through MCP](/guides/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. Leonid Bugaev · Published 21 Oct 2026 **TL;DR** - **No limit in the spec, real limits in apps:** Claude Code cut at 4,096 characters and Grok Build at about 2,048; OpenCode passed them in full. - **The end gets dropped.** A 5,092-character text lost about 1,000 characters in Claude Code and about 3,000 in Grok. - **Extreme case:** one server sent 115,077 characters (26,633 tokens) with its key rule at character 28,484. Grok showed the model the first 2,067. - **Short works:** a 728-character text that opened with the key rule got Claude Code and Codex to call the start-here tool first in 12 of 12 runs each (76–100%). - **Budget:** under 2,000 characters, the rule that must never be missed first, the long method behind a tool. [Limits by app](#limits)[What real servers lost](#lost)[A short text that worked](#short)[How to write within the budget](#budget)[How we measured](#how-we-measured)[FAQ](#faq) ## Limits by app The [MCP spec](https://modelcontextprotocol.io/specification/2026-07-28) 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 | Grok Build *~2,048 chars* Claude Code *4,096 chars* Text we tested *728 chars* Typical server *5,092 chars* Where each app puts them, and whether agents follow them: [do agents read MCP server instructions?](/blog/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. [Test your MCP →](/#contact) ## 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](/blog/get-instructions-first-24-of-24/). **Go deeper:** [Why agents don't use your MCP server](/blog/agent-does-not-recognise-mcp-server/), [Skills vs MCP instructions](/blog/agent-skills-vs-mcp-server/), [Prompts, resources or tools?](/blog/mcp-prompts-resources-tools-which-agents-use/). ## How to write within the budget 1. **Under about 2,000 characters.** That survives the smallest cut we measured. 2. **The must-not-miss rule first**, in one sentence: where to start, and what never to do without asking. 3. **The long method behind a tool**, for example `get_instructions(job)`, returning only the playbook for the current job. 4. **Repeat the start rule in tool descriptions**, first line, so apps that never show the instructions still carry it. 5. **Check per app**: capture what each app passes to the model, because limits change between versions. More: [onboard agents through your MCP server](/guides/onboard-agents-through-mcp/). ## 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. [Test your MCP →](/#contact) ## Keep reading - Up[How to onboard AI agents through your MCP server (guide)](/guides/onboard-agents-through-mcp/) - Related[Do AI agents read your MCP server instructions? Tested in Claude Code, Codex, Grok and OpenCode](/blog/do-agents-read-mcp-server-instructions/) - Related[Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex](/blog/get-instructions-first-24-of-24/)