Skip to content

Commit 291811d

Browse files
committed
docs: improve discoverability and docs for the instructions parameter
Add a class docstring to MCPServer documenting the instructions parameter, 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 291811d

3 files changed

Lines changed: 48 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: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,16 @@ async def wrap(_: Server[LifespanResultT]) -> AsyncIterator[LifespanResultT]:
145145

146146

147147
class MCPServer(Generic[LifespanResultT]):
148+
"""A more ergonomic interface for MCP servers.
149+
150+
Exposes tools, resources, and prompts to connected clients, and declares
151+
capabilities automatically based on what you register.
152+
153+
The ``instructions`` parameter returns free-text guidance to the client in
154+
the ``InitializeResult`` handshake. Use it to describe tool groupings,
155+
workflows, or usage hints for the model without a dedicated grouping API.
156+
"""
157+
148158
def __init__(
149159
self,
150160
name: str | None = None,

0 commit comments

Comments
 (0)