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