Skip to content

Commit e00ea5c

Browse files
docs(mcp): clarify timeouts and constructor options (#5417)
* docs(mcp): clarify timeouts and constructor options * docs(mcp): distinguish cold-start preparation from session timeouts
1 parent 0dc4cf1 commit e00ea5c

1 file changed

Lines changed: 11 additions & 1 deletion

File tree

‎docs/mcp.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,13 +250,16 @@ asyncio.run(main())
250250

251251
The constructor accepts additional options:
252252

253-
- `client_session_timeout_seconds` controls MCP ClientSession read timeouts. Positive finite values representable by `datetime.timedelta` and at least one microsecond set a finite timeout; `None` and `0` disable it. Other values are rejected when the server is constructed.
253+
- `client_session_timeout_seconds` controls MCP ClientSession read timeouts and defaults to `5` seconds on `MCPServerStdio`, `MCPServerSse`, and `MCPServerStreamableHttp`. Positive finite values representable by `datetime.timedelta` and at least one microsecond set a finite timeout; `None` and `0` disable it. Other values are rejected when the server is constructed.
254254
- `use_structured_content` toggles whether `tool_result.structured_content` is preferred over textual output.
255255
- `max_retry_attempts` and `retry_backoff_seconds_base` add automatic retries for `list_tools()` and `call_tool()`.
256+
- `retry_backoff_seconds_max` caps the delay between retries in seconds; `None` (the default) leaves exponential backoff uncapped.
257+
- `max_list_pages` limits successful pages per automatic `list_tools()` or `list_prompts()` call. `None` (the default) applies no page limit. With a positive integer limit, completion on the final permitted page succeeds; further continuation raises `UserError` without returning or caching a partial list.
256258
- `tool_filter` lets you expose only a subset of tools (see [Tool filtering](#tool-filtering)).
257259
- `require_approval` enables human-in-the-loop approval policies on local MCP tools.
258260
- `failure_error_function` customizes model-visible MCP tool failure messages; set it to `None` to raise errors instead.
259261
- `tool_meta_resolver` injects per-call MCP `_meta` payloads before `call_tool()`.
262+
- `custom_data_extractor` receives `MCPToolCustomDataContext` and returns SDK-only custom data for emitted MCP tool output items.
260263

261264
### Approval policies for local MCP servers
262265

@@ -366,6 +369,7 @@ async with MCPServerStdio(
366369
"command": "npx",
367370
"args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)],
368371
},
372+
client_session_timeout_seconds=30,
369373
) as server:
370374
agent = Agent(
371375
name="Assistant",
@@ -376,6 +380,12 @@ async with MCPServerStdio(
376380
print(result.final_output)
377381
```
378382

383+
!!! tip "Package runner cold starts"
384+
385+
Package runners such as `npx -y` and `uvx` may download packages before the MCP server starts. Install the package before connecting to avoid spending connection setup time on these downloads.
386+
387+
The example increases `client_session_timeout_seconds` to allow more time for initialization and subsequent session requests. With MCP Python SDK v1, this can also accommodate package downloads during initialization. With MCP Python SDK v2, the initial `server/discover` request has a separate timeout that this setting does not change. Preinstall the package for slow v2 cold starts; increasing the session timeout alone does not control every stage of connection setup.
388+
379389
## 5. MCP server manager
380390

381391
When you have multiple MCP servers, use `MCPServerManager` to connect them up front and expose the successfully connected subset of those servers to your agents. See the [MCPServerManager API reference](ref/mcp/manager.md) for constructor options and reconnect behavior.

0 commit comments

Comments
 (0)