Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#5,405 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start with docs/mcp.md and compare its constructor options list and MCPServerStdio example with the supported parameters in src/agents/mcp/server.py. Update the timeout default, add the omitted options, and document the CLI cold-start and Windows runner guidance; done when the example and options list explain the requested behavior.

Written by the indexing model from the issue text.

Description

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
Dominant language
Python
Stars
30.2k
Forks
4.9k
Avg merge
11h 46m
Merged PRs (30d)
160

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/openai-agents-python

All issues in openai/openai-agents-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.