Skip to content

Commit fb61712

Browse files
felixweinbergerfelixweinberger
committed
docs: add documentation for 19 missing features (SEP-1730 Tier 1)
Add documentation with examples for all previously undocumented features: Server (docs/server.md): - Tools: audio results, change notifications - Resources: binary reading, subscribing, unsubscribing - Prompts: embedded resources, image content, change notifications - Logging: setting level - Elicitation: enum values, complete notification Client (docs/client.md): - Roots: listing, change notifications - SSE transport (legacy client) - Ping, logging Protocol (docs/protocol.md): - Ping, cancellation, capability negotiation - Protocol version negotiation, JSON Schema 2020-12 All code snippets verified against SDK source and runtime-tested. Tier audit now shows 48/48 features documented.
1 parent 8da96dd commit fb61712

File tree

3 files changed

+513
-0
lines changed

3 files changed

+513
-0
lines changed

‎docs/client.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,82 @@ async with streamablehttp_client("http://localhost:8000/mcp") as (
6363
# get_session_id() returns the server-assigned session ID, or None
6464
```
6565

66+
### SSE Transport (Legacy)
67+
68+
The `sse_client` context manager connects to a server using the legacy
69+
Server-Sent Events transport. This transport is deprecated in favor of Streamable
70+
HTTP, but remains available for backward compatibility with older servers.
71+
72+
```python
73+
from mcp import ClientSession
74+
from mcp.client.sse import sse_client
75+
76+
async with sse_client(
77+
url="http://localhost:8000/sse",
78+
headers={"Authorization": "Bearer token"},
79+
timeout=5, # HTTP timeout for regular operations
80+
sse_read_timeout=300, # how long to wait for a new SSE event
81+
) as (read_stream, write_stream):
82+
async with ClientSession(read_stream, write_stream) as session:
83+
await session.initialize()
84+
```
85+
86+
## Roots
87+
88+
Roots tell the server which directories or files the client is making available.
89+
A server may request the list of roots at any time during a session.
90+
91+
### Providing Roots
92+
93+
Supply a `list_roots_callback` when constructing the `ClientSession`. The callback
94+
receives a `RequestContext` and must return a `ListRootsResult`.
95+
96+
```python
97+
from mcp import ClientSession, types
98+
from mcp.client.stdio import stdio_client
99+
from mcp.shared.context import RequestContext
100+
101+
async def handle_list_roots(
102+
context: RequestContext[ClientSession, None],
103+
) -> types.ListRootsResult:
104+
return types.ListRootsResult(
105+
roots=[
106+
types.Root(
107+
uri="file:///home/user/project",
108+
name="My Project",
109+
),
110+
types.Root(
111+
uri="file:///home/user/data",
112+
name="Data Directory",
113+
),
114+
]
115+
)
116+
117+
server_params = StdioServerParameters(command="uv", args=["run", "my-server"])
118+
119+
async with stdio_client(server_params) as (read_stream, write_stream):
120+
async with ClientSession(
121+
read_stream,
122+
write_stream,
123+
list_roots_callback=handle_list_roots,
124+
) as session:
125+
await session.initialize()
126+
```
127+
128+
When a `list_roots_callback` is provided, the client automatically advertises the
129+
`roots` capability (with `listChanged=True`) during initialization.
130+
131+
### Sending Roots Changed Notifications
132+
133+
When the set of roots changes after initialization, notify the server so it can
134+
re-request the list:
135+
136+
```python
137+
# After updating what handle_list_roots would return:
138+
await session.send_roots_list_changed()
139+
```
140+
141+
The server will then call the `list_roots_callback` again to get the updated list.
66142

67143
## Tools
68144

@@ -191,6 +267,30 @@ result = await session.complete(
191267
)
192268
```
193269

270+
## Ping
271+
272+
Send a ping to verify the server is responsive:
273+
274+
```python
275+
await session.send_ping()
276+
```
277+
278+
## Logging
279+
280+
Set the server's logging level and handle log messages via a callback:
281+
282+
```python
283+
async def handle_log(params: types.LoggingMessageNotificationParams) -> None:
284+
print(f"[{params.level}] {params.logger}: {params.data}")
285+
286+
async with ClientSession(
287+
read_stream,
288+
write_stream,
289+
logging_callback=handle_log,
290+
) as session:
291+
await session.initialize()
292+
await session.set_logging_level("info")
293+
```
194294

195295
## Client Display Utilities
196296

‎docs/protocol.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,29 @@
22

33
This page covers cross-cutting protocol mechanics that apply to both clients and servers.
44

5+
## Ping
6+
7+
Both client and server expose a `send_ping()` method for health/liveness checks. The remote side responds automatically -- no handler registration is needed. Pings are allowed at any point in the session lifecycle, even before initialization completes.
8+
9+
**Client pinging the server:**
10+
11+
```python
12+
from mcp import ClientSession
13+
14+
async with ClientSession(read_stream, write_stream) as session:
15+
await session.initialize()
16+
result = await session.send_ping() # returns EmptyResult
17+
```
18+
19+
**Server pinging the client:**
20+
21+
```python
22+
from mcp.server.session import ServerSession
23+
24+
# Inside a server handler where you have access to the session:
25+
result = await server_session.send_ping() # returns EmptyResult
26+
```
27+
528
## Progress notifications
629

730
Long-running requests can report incremental progress to the caller. The SDK handles `progressToken` plumbing automatically when you provide a callback.
@@ -36,6 +59,45 @@ result = await session.call_tool(
3659

3760
The `progress_callback` receives three arguments: `progress` (float), `total` (float | None), and `message` (str | None).
3861

62+
## Cancellation
63+
64+
Either side can cancel an in-flight request by sending a `notifications/cancelled` message. In the Python SDK, the session's receive loop listens for `CancelledNotification` and cancels the corresponding request's scope.
65+
66+
**Client cancelling a request:**
67+
68+
```python
69+
import anyio
70+
from mcp import types
71+
72+
async with ClientSession(read_stream, write_stream) as session:
73+
await session.initialize()
74+
75+
async with anyio.create_task_group() as tg:
76+
async def run_tool():
77+
result = await session.call_tool("slow-tool", {})
78+
79+
async def cancel_after_delay():
80+
await anyio.sleep(5)
81+
# Send cancellation for request ID 0
82+
await session.send_notification(
83+
types.ClientNotification(
84+
types.CancelledNotification(
85+
params=types.CancelledNotificationParams(
86+
requestId=0,
87+
reason="Timed out waiting",
88+
)
89+
)
90+
)
91+
)
92+
93+
tg.start_soon(run_tool)
94+
tg.start_soon(cancel_after_delay)
95+
```
96+
97+
**Server-side cancellation handling:**
98+
99+
When the SDK receives a `CancelledNotification`, it automatically calls `cancel()` on the in-flight `RequestResponder`, which cancels its `anyio.CancelScope`. Tool handlers running inside that scope will receive a `Cancelled` exception from anyio. No additional handler registration is needed.
100+
39101
## Pagination
40102

41103
All list methods (`list_tools`, `list_prompts`, `list_resources`, `list_resource_templates`) support cursor-based pagination. Pass the `nextCursor` from the previous response to fetch the next page.
@@ -57,3 +119,135 @@ while True:
57119
```
58120

59121
The same pattern applies to `list_prompts`, `list_resources`, and `list_resource_templates`.
122+
123+
## Capability negotiation
124+
125+
Both client and server declare their capabilities during the `initialize` handshake. The SDK uses these declarations to determine which features are available.
126+
127+
**Client capabilities** are determined automatically based on the callbacks you provide when constructing `ClientSession`:
128+
129+
```python
130+
from mcp import ClientSession
131+
132+
session = ClientSession(
133+
read_stream,
134+
write_stream,
135+
# Providing these callbacks automatically declares the corresponding capabilities
136+
sampling_callback=my_sampling_handler, # declares sampling capability
137+
elicitation_callback=my_elicit_handler, # declares elicitation capability
138+
list_roots_callback=my_roots_handler, # declares roots capability
139+
)
140+
await session.initialize()
141+
142+
# After initialization, inspect server capabilities:
143+
server_caps = session.get_server_capabilities()
144+
if server_caps and server_caps.tools:
145+
tools = await session.list_tools()
146+
if server_caps and server_caps.resources and server_caps.resources.subscribe:
147+
# Server supports resource subscriptions
148+
pass
149+
```
150+
151+
**Server capabilities** are inferred from registered handlers. When using FastMCP, capabilities are set automatically based on what you register (tools, resources, prompts). With the low-level `Server`, the `get_capabilities` method inspects which request handlers are registered:
152+
153+
```python
154+
from mcp.server.lowlevel import Server
155+
156+
server = Server("my-server")
157+
158+
# Registering a handler for ListToolsRequest causes the server
159+
# to advertise the tools capability automatically.
160+
@server.list_tools()
161+
async def handle_list_tools():
162+
return [...]
163+
164+
# The capabilities are built when creating initialization options:
165+
options = server.create_initialization_options()
166+
# options.capabilities.tools will be set because list_tools handler exists
167+
```
168+
169+
## Protocol version negotiation
170+
171+
The SDK automatically negotiates protocol versions during the `initialize` handshake. The client sends `LATEST_PROTOCOL_VERSION` and the server responds with the highest mutually supported version.
172+
173+
Supported versions are defined in `SUPPORTED_PROTOCOL_VERSIONS`:
174+
175+
```python
176+
from mcp.types import LATEST_PROTOCOL_VERSION
177+
from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
178+
179+
print(LATEST_PROTOCOL_VERSION)
180+
# "2025-11-25"
181+
182+
print(SUPPORTED_PROTOCOL_VERSIONS)
183+
# ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"]
184+
```
185+
186+
During initialization, the server checks whether the client's requested version is in `SUPPORTED_PROTOCOL_VERSIONS`. If it is, the server echoes that version back. Otherwise, the server responds with `LATEST_PROTOCOL_VERSION`. On the client side, if the server's response contains a version not in `SUPPORTED_PROTOCOL_VERSIONS`, the client raises a `RuntimeError`.
187+
188+
This negotiation is handled automatically by `ClientSession.initialize()`:
189+
190+
```python
191+
async with ClientSession(read_stream, write_stream) as session:
192+
init_result = await session.initialize()
193+
print(init_result.protocolVersion)
194+
# The negotiated version, e.g. "2025-11-25"
195+
print(init_result.serverInfo)
196+
# Implementation(name="my-server", version="1.0.0")
197+
```
198+
199+
If you need to specify a default version for clients that do not declare one, the SDK uses `DEFAULT_NEGOTIATED_VERSION` (`"2025-03-26"`).
200+
201+
## JSON Schema 2020-12
202+
203+
MCP uses [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) for tool input schemas (`inputSchema`) and output schemas (`outputSchema`). When using FastMCP with Python type annotations, schemas are generated automatically via Pydantic:
204+
205+
```python
206+
from pydantic import BaseModel, Field
207+
from mcp.server.fastmcp import FastMCP
208+
209+
mcp = FastMCP("example")
210+
211+
@mcp.tool()
212+
async def calculate(a: float, b: float) -> float:
213+
"""Add two numbers."""
214+
return a + b
215+
216+
# The SDK generates an inputSchema like:
217+
# {
218+
# "type": "object",
219+
# "properties": {
220+
# "a": {"type": "number"},
221+
# "b": {"type": "number"}
222+
# },
223+
# "required": ["a", "b"]
224+
# }
225+
```
226+
227+
With the low-level `Server`, you provide JSON Schema directly when defining tools:
228+
229+
```python
230+
from mcp import types
231+
232+
tool = types.Tool(
233+
name="calculate",
234+
description="Add two numbers",
235+
inputSchema={
236+
"type": "object",
237+
"properties": {
238+
"a": {"type": "number"},
239+
"b": {"type": "number"},
240+
},
241+
"required": ["a", "b"],
242+
},
243+
outputSchema={
244+
"type": "object",
245+
"properties": {
246+
"result": {"type": "number"},
247+
},
248+
"required": ["result"],
249+
},
250+
)
251+
```
252+
253+
When `outputSchema` is provided, the client SDK validates the tool's `structuredContent` response against that schema using `jsonschema.validate`.

0 commit comments

Comments
 (0)