docs(mcp): clarify client_session_timeout_seconds default (5s), npx/cli cold-start timeout, and document missing constructor options

从 docs/mcp.md 开始，将其中的构造函数选项列表和 MCPServerStdio 示例与 src/agents/mcp/server.py 中支持的参数进行比较。更新超时默认值，补充遗漏的选项，并记录 CLI 冷启动和 Windows runner 的指南；当示例和选项列表说明了所要求的行为时，即为完成。

Summary

In docs/mcp.md, the documentation provides a canonical example using MCPServerStdio with npx (@modelcontextprotocol/server-filesystem), but omits critical timeout details for CLI package runners as well as several constructor parameters supported in src/agents/mcp/server.py.

1. MCPServerStdio Cold-Start Timeout with npx

Problem

In docs/mcp.md (lines 363–369):

async with MCPServerStdio(
    name="Filesystem Server via npx",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)],
    },
) as server:


MCPServerStdio defaults to client_session_timeout_seconds=5 (src/agents/mcp/server.py:1973).

When running npx -y (or uvx) in an environment where the package has not yet been cached, npm downloads and unpacks the package during initialization. This cold start regularly takes 10–25 seconds.

Consequently, the official example fails out of the box with:
mcp.shared.exceptions.MCPError: Request 'initialize' timed out

Additionally, on Windows, "command": "npx" requires "npx.cmd" when spawned by subprocess runners.


Solution
Document that client_session_timeout_seconds defaults to 5 seconds.
Show client_session_timeout_seconds=30 in the stdio example so new users don't encounter initialization timeouts during package downloads.
Add a tip callout box explaining cold-start behavior for CLI package runners and noting Windows "npx.cmd" usage.


2. Missing Constructor Options in docs/mcp.md
src/agents/mcp/server.py implements several constructor parameters across MCPServerStdio, MCPServerSse, and MCPServerStreamableHttp that are currently omitted from the options list in docs/mcp.md (lines 251–260):

max_list_pages: Maximum pages allowed for automatic list_tools() or list_prompts() pagination (bounds pagination and prevents runaway fetching).
retry_backoff_seconds_max: Caps exponential backoff delay between retry attempts.
custom_data_extractor: Optional callable providing SDK-only custom data metadata on emitted tool results.


Proposed Documentation Diff

diff --git a/docs/mcp.md b/docs/mcp.md
index 8191d057..33dbedfd 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -250,13 +250,16 @@ asyncio.run(main())
 
 The constructor accepts additional options:
 
-- `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.
+- `client_session_timeout_seconds` controls MCP ClientSession read timeouts. Defaults to `5` seconds. 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.
 - `use_structured_content` toggles whether `tool_result.structured_content` is preferred over textual output.
 - `max_retry_attempts` and `retry_backoff_seconds_base` add automatic retries for `list_tools()` and `call_tool()`.
+- `retry_backoff_seconds_max` caps the maximum delay in seconds between retries; `None` (the default) leaves exponential backoff uncapped.
+- `max_list_pages` sets the maximum number of pages allowed per automatic `list_tools()` or `list_prompts()` call. `None` (the default) applies no page limit; exceeding a configured positive integer limit raises `UserError`.
 - `tool_filter` lets you expose only a subset of tools (see [Tool filtering](#tool-filtering)).
 - `require_approval` enables human-in-the-loop approval policies on local MCP tools.
 - `failure_error_function` customizes model-visible MCP tool failure messages; set it to `None` to raise errors instead.
 - `tool_meta_resolver` injects per-call MCP `_meta` payloads before `call_tool()`.
+- `custom_data_extractor` provides an optional callable that extracts SDK-only custom data for emitted MCP tool output items.
 
 ### Approval policies for local MCP servers
 
@@ -366,6 +369,7 @@ async with MCPServerStdio(
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)],
     },
+    client_session_timeout_seconds=30,
 ) as server:
     agent = Agent(
         name="Assistant",
@@ -376,6 +380,10 @@ async with MCPServerStdio(
     print(result.final_output)
+!!! tip "Cold-start timeouts and package managers" +

MCPServerStdio defaults to client_session_timeout_seconds=5. When you use command-line package runners such as npx -y or uvx that download packages on first run, the initial package installation often exceeds five seconds. Increase client_session_timeout_seconds (for example, to 30) or set it to None to prevent Request 'initialize' timed out errors during cold starts. On Windows, ensure "command" points to an executable or batch runner such as "npx.cmd".
5. MCP server manager
---
### Reference Implementation
Verified commit available on fork:
https://github.com/MuneebMalik244535/openai-agents-python/commit/7e2324fba0053f3652edbd8fd5ff78b1b1cb758b