anthropics / anthropics/claude-ai-mcp

Server instructions from initialize response not passed to model

Aperta
#93 11 commenti 20 reazioni 0 assegnatari Vedi su GitHub
backlog enhancement triaged
Lingua principale
Nessun dato sulla lingua
Stelle
471
Fork
76
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

### What happened?

MCP servers can return `instructions` in the `InitializationOptions` from the `initialize` response (per the MCP spec). These instructions are intended to be injected into the model's system prompt so the LLM understands how to use the server's tools effectively.

Claude.ai appears to silently ignore the `instructions` field. The model receives tool names, descriptions, and input schemas — but not the server-level instructions that provide context across tools (e.g., data model relationships, workflow guidance, enum values that don't fit in truncated tool descriptions).

This is confirmed by observing model behavior: instructions that should guide tool usage (like "always use `has_price` to filter tradeable bonds" or "use `paridad_usd` for cross-currency comparison") have no effect unless duplicated into individual tool descriptions, which are themselves truncated.

### What did you expect to happen?

The `instructions` field from the server's `initialize` response should be included in the model's system prompt (or equivalent context), similar to how Claude Code handles it. This is how the MCP spec intends server-level guidance to reach the model.

### Steps to reproduce

1. Create an MCP server that returns `instructions` in `create_initialization_options()`:
```python
class MyServer(Server):
def create_initialization_options(self, ...):
opts = super().create_initialization_options(...)
opts.instructions = "IMPORTANT: Always use field X when querying Y."
return opts
```
2. Connect the server to claude.ai via custom connector
3. Ask the model to perform a task that the instructions would guide
4. Observe the model does not follow the server instructions (e.g., uses wrong field names, misses workflow steps)
5. Compare with Claude Code (stdio), where the same server's instructions are respected

### Area

Tool Discovery / Invocation

### MCP Server (if applicable)

Custom server (Streamable HTTP transport, Python `mcp` SDK). Reproducible with any server that sets `instructions` in `InitializationOptions`.

### Error messages or logs

No error — the field is silently ignored. No indication in the client that instructions were received or discarded.

### Additional context

- Claude Code **does** process server instructions correctly (fixed in [anthropics/claude-code#3312](https://github.com/anthropics/claude-code/issues/3312))
- The Agent SDK also doesn't process them ([anthropics/claude-agent-sdk-typescript#174](https://github.com/anthropics/claude-agent-sdk-typescript/issues/174))
- This forces server developers to cram all guidance into individual tool descriptions, which are truncated by claude.ai after ~500 characters — making it impossible to provide adequate context for complex servers with 15+ tools
- Workaround: duplicate critical info in tool descriptions (limited by truncation) or return it in tool results (costs an extra round-trip)

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.