diff --git a/docs/get-started/first-steps.md b/docs/get-started/first-steps.md index ad2f4c63fd..fb992d1ba9 100644 --- a/docs/get-started/first-steps.md +++ b/docs/get-started/first-steps.md @@ -116,6 +116,22 @@ Notice what isn't there. `completions` (argument autocomplete for resource templ `Client(mcp)` is the same in-memory client every example in these docs is tested with, and it's how you'll test yours. It gets a whole page: **[Testing](testing.md)**. +## Server instructions + +When a client connects, the server sends an `InitializeResult` during the +handshake. Its `instructions` field is a free-text string that clients can use +to guide the model on how to use your server's tools — for example, grouping +related tools or describing a workflow: + +```python title="server.py" hl_lines="4" +--8<-- "docs_src/first_steps/tutorial002.py" +``` + +This is the simplest way to express "these tools go together" or "follow this +order" without building a dedicated grouping API. See the +[specification](https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult-instructions) +for the wire format. + ## What you did not write Look back over this page. You wrote three small Python functions. You did **not** write: diff --git a/docs_src/first_steps/tutorial002.py b/docs_src/first_steps/tutorial002.py new file mode 100644 index 0000000000..d754fbae9d --- /dev/null +++ b/docs_src/first_steps/tutorial002.py @@ -0,0 +1,22 @@ +from mcp.server import MCPServer + +mcp = MCPServer( + name="Demo", + instructions=( + "This server exposes two groups of tools: 'read_*' for fetching data " + "and 'write_*' for persisting it. Always call a read tool before a " + "write tool, and prefer batch_write over repeated single writes." + ), +) + + +@mcp.tool() +def read_status() -> str: + """Read the current system status.""" + return "ok" + + +@mcp.tool() +def write_record(data: str) -> str: + """Persist a record.""" + return f"wrote: {data}" diff --git a/src/mcp/server/mcpserver/server.py b/src/mcp/server/mcpserver/server.py index bc79c44a36..9a15dda7e1 100644 --- a/src/mcp/server/mcpserver/server.py +++ b/src/mcp/server/mcpserver/server.py @@ -145,6 +145,16 @@ async def wrap(_: Server[LifespanResultT]) -> AsyncIterator[LifespanResultT]: class MCPServer(Generic[LifespanResultT]): + """A more ergonomic interface for MCP servers. + + Exposes tools, resources, and prompts to connected clients, and declares + capabilities automatically based on what you register. + + The ``instructions`` parameter returns free-text guidance to the client in + the ``InitializeResult`` handshake. Use it to describe tool groupings, + workflows, or usage hints for the model without a dedicated grouping API. + """ + def __init__( self, name: str | None = None,