Inconsistent timeout and sse_read_timeout Types in MCPServerSseParams and MCPServerStreamableHttpParams

Description

In the server.py file of the openai-agents-python project (version 1.9.3), the timeout and sse_read_timeout parameters in MCPServerSseParams and MCPServerStreamableHttpParams have inconsistent types, causing confusion and potential runtime errors:

• MCPServerSseParams:
  • timeout: NotRequired[float]
  • sse_read_timeout: NotRequired[float]
• MCPServerStreamableHttpParams:
  • timeout: NotRequired[timedelta]
  • sse_read_timeout: NotRequired[timedelta]

This inconsistency requires developers to handle different types (float vs timedelta) when configuring servers, which can lead to errors. For example, passing a float timeout to MCPServerStreamableHttp causes a TaskGroup exception in streamablehttp_client (e.g., unhandled errors in a TaskGroup (1 sub-exception)), as observed in logs:

2025-06-11 19:17:20,478 server.py:132 - mcp_client - [MainThread:5432] - ERROR - Error initializing MCP server: unhandled errors in a TaskGroup (1 sub-exception)

The lack of clear error messages from streamablehttp_client further complicates debugging.

Steps to Reproduce

1. Configure an MCPServerStreamableHttp with a float timeout (e.g., timeout=30).
2. Call server.connect() in a context like McpServerMgr.initialize_servers.
3. Observe a TaskGroup exception due to type mismatch in streamablehttp_client.

Expected Behavior

Both MCPServerSseParams and MCPServerStreamableHttpParams should use the same type for timeout and sse_read_timeout (preferably float, as it’s more intuitive for configuration files). The streamablehttp_client should either handle float internally or provide clear error messages for type mismatches.

Proposed Solution

1. Unify the types in MCPServerSseParams and MCPServerStreamableHttpParams to float for timeout and sse_read_timeout.
2. In MCPServerStreamableHttp.create_streams, convert float to timedelta internally if required by streamablehttp_client.
3. Add type validation in create_streams to raise clear TypeError messages.
4. Update documentation to specify parameter types and defaults.

Example implementation:

class MCPServerStreamableHttpParams(TypedDict):
    url: str
    headers: NotRequired[dict[str, str]]
    timeout: NotRequired[float]
    sse_read_timeout: NotRequired[float]
    terminate_on_close: NotRequired[bool]

class MCPServerStreamableHttp(_MCPServerWithClientSession):
    def create_streams(self):
        timeout = self.params.get("timeout", 30.0)
        sse_read_timeout = self.params.get("sse_read_timeout", 60 * 5.0)
        if not isinstance(timeout, (int, float)):
            raise TypeError(f"timeout must be float, got {type(timeout)}")
        if not isinstance(sse_read_timeout, (int, float)):
            raise TypeError(f"sse_read_timeout must be float, got {type(sse_read_timeout)}")
        return streamablehttp_client(
            url=self.params["url"],
            headers=self.params.get("headers", None),
            timeout=timedelta(seconds=float(timeout)),
            sse_read_timeout=timedelta(seconds=float(sse_read_timeout)),
            terminate_on_close=self.params.get("terminate_on_close", True),
        )

Additional Notes

• This issue was encountered while using MCPServerStreamableHttp with a server at http://localhost:3001/mcp, which is confirmed to be reachable.
• The inconsistent types increase maintenance overhead and debugging difficulty, especially without detailed error logs from streamablehttp_client.
• Suggest adding type validation and better error handling in streamablehttp_client to improve developer experience.

Environment

• Package version: mcp 1.9.3
• Python version: [Specify your Python version, e.g., 3.10]
• Operating system: [Specify your OS, e.g., macOS]

Please let me know if you need additional details to address this issue!