[Bug]: MCP server instructions are 5,859 chars — Claude Code truncates at 2,048, discarding all run-commissioning guidance #7098

Before you submit

• I searched existing issues and confirmed this is not a duplicate.
• I replaced the example text with the real behavior, reproduction steps, expected result, and version.

What happened?

od mcp's MCP instructions field is 5,859 characters. Claude Code truncates MCP server instructions at 2,048 characters — a documented, intended per-server cap — so 3,811 characters (65%) never reach the model.

The cut lands mid-sentence, immediately before the run-commissioning section:

...explicitly without making any other tool call.

To make Open        <-- truncated here

Everything after that point is discarded. That is the entire "how to actually drive Open Design" half:

The client's documentation is explicit about this (code.claude.com/docs/en/mcp, "For MCP server authors"):

Claude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.

Confirmed as intended client behavior by an Anthropic maintainer on anthropics/claude-code#43474 (closed 2026-08-17): "a per-server cap, not a shared budget… intended behavior since 2.1.84." So this is an Open Design-side fix, not a client bug.

Steps to reproduce

1. Register od mcp with Claude Code (any scope).
2. Start a session and inspect the # MCP Server Instructions block, or run with --debug and check ~/.claude/debug/<session>.txt.
3. Observe the block ends ...To make Open… [truncated], and the debug log records:
   MCP server "open-design": Server instructions truncated from 5859 to 2048 chars

Measure directly from source:

python3 - <<'PY'
import re, pathlib
t = pathlib.Path('apps/daemon/src/mcp.ts').read_text()
m = re.search(r"instructions:\s*\[([\s\S]{200,40000}?)\]\s*\.join", t)
full = "\n".join(re.findall(r"'((?:[^'\\]|\\.)*)'", m.group(1)))
print(len(full), "chars;", len(full)-2048, "discarded")
PY

Expected result

The guidance that most affects correct usage survives the client's documented 2 KB budget.

Impact

A calling agent sees the read-only tools and none of the run workflow, so the predictable failure mode is: skip list_skills/list_plugins entirely, hand-write prompts instead of using skills/plugins, guess at start_run.agent, omit requestId, and never discover collect_brief or the od:// resources. The instructions anticipate exactly these mistakes — in the half that is discarded.

Observed first-hand across a working session before reading mcp.ts directly: 155 skills and 457 plugins available, zero used.

Suggested fix

Reordering alone would resolve most of it, since the cap keeps the first 2,048 characters:

1. Front-load run commissioning. Move list_skills / list_plugins / list_agents / start_run / get_run above the read-only tool catalogue. Tool-level descriptions already cover per-tool detail; the instructions block is better spent on what the tool schemas cannot say.
2. Trim to ~2 KB. The read-only section largely restates individual tool descriptions the client also receives.
3. Optionally move the long-form material into an od:// resource and reference it in one line — the instructions already establish that pattern for design systems and skills.

Note the block was ~2.8 KB when od mcp was introduced (33c3b94) and grew to 5,859 with #3141, which added the now-discarded generation-loop section.

Version

• Open Design 0.19.2 (commit 932c9c5)
• Claude Code 2.1.233 (cap constant vue = 2048, flat slice)
• Linux

— Written by Claude Code (Opus 5) on behalf of @0reo