Skip to content

Commit db0f5b0

Browse files
committed
docs: improve discoverability and docs for the instructions parameter
Add a docstring to the instructions parameter in MCPServer.__init__ and a new Server instructions section to the first-steps guide, with a concrete example showing how to use instructions to express tool grouping and workflow guidance. Closes #1464
1 parent 52ad0a8 commit db0f5b0

3 files changed

Lines changed: 45 additions & 0 deletions

File tree

docs/get-started/first-steps.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,22 @@ Notice what isn't there. `completions` (argument autocomplete for resource templ
116116
`Client(mcp)` is the same in-memory client every example in these docs is tested with, and
117117
it's how you'll test yours. It gets a whole page: **[Testing](testing.md)**.
118118

119+
## Server instructions
120+
121+
When a client connects, the server sends an `InitializeResult` during the
122+
handshake. Its `instructions` field is a free-text string that clients can use
123+
to guide the model on how to use your server's tools — for example, grouping
124+
related tools or describing a workflow:
125+
126+
```python title="server.py" hl_lines="4"
127+
--8<-- "docs_src/first_steps/tutorial002.py"
128+
```
129+
130+
This is the simplest way to express "these tools go together" or "follow this
131+
order" without building a dedicated grouping API. See the
132+
[specification](https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult-instructions)
133+
for the wire format.
134+
119135
## What you did not write
120136

121137
Look back over this page. You wrote three small Python functions. You did **not** write:
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
from mcp.server import MCPServer
2+
3+
mcp = MCPServer(
4+
name="Demo",
5+
instructions=(
6+
"This server exposes two groups of tools: 'read_*' for fetching data "
7+
"and 'write_*' for persisting it. Always call a read tool before a "
8+
"write tool, and prefer batch_write over repeated single writes."
9+
),
10+
)
11+
12+
13+
@mcp.tool()
14+
def read_status() -> str:
15+
"""Read the current system status."""
16+
return "ok"
17+
18+
19+
@mcp.tool()
20+
def write_record(data: str) -> str:
21+
"""Persist a record."""
22+
return f"wrote: {data}"

src/mcp/server/mcpserver/server.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,13 @@ def __init__(
151151
title: str | None = None,
152152
description: str | None = None,
153153
instructions: str | None = None,
154+
"""Optional free-text instructions returned to the client in the server's `InitializeResult`.
155+
156+
Use these to guide the client or model on how to use the server's tools —
157+
for example, grouping related tools, describing a workflow, or noting when
158+
each tool should be called. This can address many requests for tool bundling,
159+
grouping, or namespaces without a dedicated API.
160+
"""
154161
website_url: str | None = None,
155162
icons: list[Icon] | None = None,
156163
version: str = "",

0 commit comments

Comments
 (0)