From f7f17878aaf4e6624a1e09444d0e1456e763d309 Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Fri, 15 May 2026 00:48:41 -0700
Subject: [PATCH] docs: add server instructions example

---
 README.v2.md                              | 37 +++++++++++++++++++++++
 examples/snippets/servers/instructions.py | 21 +++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 examples/snippets/servers/instructions.py

diff --git a/README.v2.md b/README.v2.md
index d0851c04e5..eb1e42404d 100644
--- a/README.v2.md
+++ b/README.v2.md
@@ -48,6 +48,7 @@
     - [Logging and Notifications](#logging-and-notifications)
     - [Authentication](#authentication)
     - [MCPServer Properties](#mcpserver-properties)
+    - [Server Instructions](#server-instructions)
     - [Session Properties and Methods](#session-properties-and-methods)
     - [Request Context Properties](#request-context-properties)
   - [Running Your Server](#running-your-server)
@@ -1088,6 +1089,42 @@ def server_info(ctx: Context) -> dict:
     }
 ```
 
+### Server Instructions
+
+Server instructions are sent to clients during initialization and are useful for describing how related tools should be used together. They can provide workflow hints, domain context, or guardrails that apply across the server's tools without repeating the same guidance in every tool description.
+
+For example, instructions can describe a preferred order for tools in a workflow:
+
+<!-- snippet-source examples/snippets/servers/instructions.py -->
+```python
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer(
+    name="Workflow Assistant",
+    instructions=(
+        "Use the project tools together: call get_project_status first, "
+        "then use create_task only for missing or blocked work."
+    ),
+)
+
+
+@mcp.tool()
+def get_project_status(project_id: str) -> str:
+    """Summarize current project status."""
+    return f"Project {project_id} is on track."
+
+
+@mcp.tool()
+def create_task(project_id: str, title: str) -> str:
+    """Create a follow-up task for the project."""
+    return f"Created task '{title}' for project {project_id}."
+```
+
+_Full example: [examples/snippets/servers/instructions.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/instructions.py)_
+<!-- /snippet-source -->
+
+Clients can read the same value from `InitializeResult.instructions` after connecting. Inside tools, the server can access it as `ctx.mcp_server.instructions`.
+
 ### Session Properties and Methods
 
 The session object accessible via `ctx.session` provides advanced control over client communication:
diff --git a/examples/snippets/servers/instructions.py b/examples/snippets/servers/instructions.py
new file mode 100644
index 0000000000..8c3c0b373f
--- /dev/null
+++ b/examples/snippets/servers/instructions.py
@@ -0,0 +1,21 @@
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer(
+    name="Workflow Assistant",
+    instructions=(
+        "Use the project tools together: call get_project_status first, "
+        "then use create_task only for missing or blocked work."
+    ),
+)
+
+
+@mcp.tool()
+def get_project_status(project_id: str) -> str:
+    """Summarize current project status."""
+    return f"Project {project_id} is on track."
+
+
+@mcp.tool()
+def create_task(project_id: str, title: str) -> str:
+    """Create a follow-up task for the project."""
+    return f"Created task '{title}' for project {project_id}."