Repository navigation
feat: inject MCP server instructions into system prompt #30084
Description
Summary
OpenCode currently ignores the instructions field returned by MCP servers during initialization. Per the MCP 2025-11-25 spec, this field is explicitly designed for LLM-facing guidance:
instructions?: string鈥?Instructions describing how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a hint to the model. For example, this information MAY be added to the system prompt.
Why this matters
1. Server authors rely on it
MCP server developers populate instructions to teach the LLM how to use their tools effectively 鈥?domain-specific guidance, best practices, ordering constraints between tools, authentication flows, etc. OpenCode throwing this away means server authors' intent is silently lost.
2. Precedent: Claude Code already does this
Claude Code (Anthropic's reference MCP client) injects server instructions into the system prompt. This is the de facto standard behavior for MCP-aware AI coding tools, and it's how server authors expect clients to behave.
3. Tool descriptions alone are insufficient
A tool's description field describes what the tool does. The server-level instructions describes how the model should reason about the server as a whole 鈥?which is qualitatively different and often contains cross-tool guidance that can't logically live on any single tool definition.
4. Missing it creates a broken contract
Servers that populate instructions are following the spec in good faith. Clients that ignore the field silently violate the contract. Server authors who test against Claude Code get proper behavior, then users report that OpenCode doesn't follow their server's guidance 鈥?and the server author has no workaround.
5. Low implementation cost
The MCP SDK already exposes client.getInstructions(): string | undefined. Capturing the value on connect and formatting it into the system prompt (wrapped in <mcp-server name=...> tags for proper attribution) is straightforward.
Proposed behavior
When connected to an MCP server that returns instructions:
- Capture the value via
client.getInstructions()after initialization - Include it in the system prompt, tagged per server:
<mcp-server name=example>
Use the example server's tools to ...
</mcp-server>
- Skip servers with no instructions or whitespace-only instructions (no noise)
- Re-capture/re-fetch on reconnection
Activity
xiedada05 commentedon May 31, 2026
One more data point: I maintain an MCP server myself that populates instructions with domain-specific guidance about how the model should approach the toolset. It works great in Claude Code, but when I use it with OpenCode the guidance is silently dropped — the model has no idea how to use the tools properly.
I'd rather not have to tell users 'only use this server with Claude Code.' MCP is an open protocol, and servers should work across all compliant clients.
github-actions commentedon May 31, 2026
This issue doesn't fully meet our contributing guidelines.
What needs to be fixed:
[FEATURE]:.Please edit this issue to address the above within 2 hours, or it will be automatically closed.
This issue might be a duplicate of existing issues. Please check:
InitializeResult.instructionsnot being captured or injected into LLM context as one of the behavioral gaps — the exact feature requested here.If you believe this was flagged incorrectly, please let a maintainer know.