René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Inconsistent timeout and sse_read_timeout Types in sse_client and streamablehttp_client","articleBody":"# Inconsistent `timeout` and `sse_read_timeout` Types in `sse_client` and `streamablehttp_client`\n\n## Description\n\nIn the `modelcontextprotocol/python-sdk` repository (version 1.9.3), the `timeout` and `sse_read_timeout` parameters in `mcp/client/sse.py` and `mcp/client/streamable_http.py` have inconsistent types, causing confusion and runtime errors in downstream applications:\n\n- `mcp/client/sse.py` (`sse_client`):\n  ```python\n  @asynccontextmanager\n  async def sse_client(\n      url: str,\n      headers: dict[str, Any] | None = None,\n      timeout: float = 5,\n      sse_read_timeout: float = 60 * 5,\n      ...\n  )\n  ```\n  - `timeout` and `sse_read_timeout` are typed as `float` (seconds).\n\n- `mcp/client/streamable_http.py` (`streamablehttp_client`):\n  ```python\n  @asynccontextmanager\n  async def streamablehttp_client(\n      url: str,\n      headers: dict[str, Any] | None = None,\n      timeout: timedelta = timedelta(seconds=30),\n      sse_read_timeout: timedelta = timedelta(seconds=60 * 5),\n      ...\n  )\n  ```\n  - `timeout` and `sse_read_timeout` are typed as `timedelta`.\n\nThis inconsistency forces developers to handle different types for similar parameters across MCP transport implementations, leading to errors. For example, in the `openai-agents-python` project, passing a `float` timeout to `MCPServerStreamableHttp` (which uses `streamablehttp_client`) causes a `TaskGroup` exception:\n\n```\n2025-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)\n```\n\nThe lack of clear error messages from `streamablehttp_client` (e.g., type mismatch) further complicates debugging.\n\n## Steps to Reproduce\n\n1. Configure an `MCPServerStreamableHttp` (from `openai-agents-python`) with a `float` timeout (e.g., `timeout=30`).\n2. Call `server.connect()`, which invokes `streamablehttp_client`.\n3. Observe a `TaskGroup` exception due to `timedelta` type mismatch.\n4. Compare with `MCPServerSse`, which accepts `float` without issues.\n\n## Expected Behavior\n\nBoth `sse_client` and `streamablehttp_client` should use consistent types for `timeout` and `sse_read_timeout` (preferably `float`, as it’s more intuitive for configuration files and aligns with `sse_client`). The functions should either handle type conversion internally or provide clear `TypeError` messages for invalid types.\n\n## Proposed Solution\n\n1. **Unify Parameter Types**:\n   - Update `streamablehttp_client` to accept `timeout` and `sse_read_timeout` as `float` (seconds), matching `sse_client`.\n   - Internally convert `float` to `timedelta` in `streamablehttp_client` if required by the underlying HTTP client (e.g., `httpx`).\n\n2. **Add Type Validation**:\n   - In both `sse_client` and `streamablehttp_client`, validate that `timeout` and `sse_read_timeout` are `int` or `float`, raising a clear `TypeError` otherwise.\n\n3. **Update Documentation**:\n   - Clearly document that `timeout` and `sse_read_timeout` are in seconds (`float`) for both functions.\n   - Specify default values and any internal conversions.\n\n4. **Ensure Backward Compatibility**:\n   - Allow `streamablehttp_client` to accept `timedelta` for a transition period, logging a deprecation warning and converting to `float` internally.\n\nExample implementation for `streamablehttp_client`:\n\n```python\nfrom datetime import timedelta\nfrom typing import Union\n\n@asynccontextmanager\nasync def streamablehttp_client(\n    url: str,\n    headers: dict[str, Any] | None = None,\n    timeout: Union[float, timedelta] = 30.0,  # Accept float, support timedelta temporarily\n    sse_read_timeout: Union[float, timedelta] = 60 * 5.0,\n    terminate_on_close: bool = True,\n    httpx_client_factory: McpHttpClientFactory = create_mcp_http_client,\n    auth: httpx.Auth | None = None,\n):\n    if isinstance(timeout, timedelta):\n        logger.warning(\"Using timedelta for timeout is deprecated; use float (seconds) instead\")\n        timeout = timeout.total_seconds()\n    if isinstance(sse_read_timeout, timedelta):\n        logger.warning(\"Using timedelta for sse_read_timeout is deprecated; use float (seconds) instead\")\n        sse_read_timeout = sse_read_timeout.total_seconds()\n    \n    if not isinstance(timeout, (int, float)):\n        raise TypeError(f\"timeout must be float, got {type(timeout)}\")\n    if not isinstance(sse_read_timeout, (int, float)):\n        raise TypeError(f\"sse_read_timeout must be float, got {type(sse_read_timeout)}\")\n    \n    # Convert to timedelta for internal use if needed\n    timeout_td = timedelta(seconds=float(timeout))\n    sse_read_timeout_td = timedelta(seconds=float(sse_read_timeout))\n    \n    # Proceed with streamablehttp_client logic\n    ...\n```\n\n## Additional Notes\n\n- This issue was discovered while using `MCPServerStreamableHttp` with a server at `http://localhost:3001/mcp` (confirmed reachable via `curl`).\n- The type inconsistency propagates to downstream projects like `openai-agents-python`, causing errors in `MCPServerStreamableHttp` initialization.\n- Suggest updating `MCPServerSseParams` and `MCPServerStreamableHttpParams` in `openai-agents-python` to align with the unified `float` type after this change.\n- Clearer error messages in `streamablehttp_client` (e.g., for type mismatches or HTTP errors) would greatly improve debugging.\n\n## Environment\n\n- Package version: `mcp` 1.9.3\n- Python version: [Specify your Python version, e.g., 3.10]\n- Operating system: [Specify your OS, e.g., macOS]\n\nPlease let me know if you need additional details or assistance to resolve this issue!","author":{"url":"https://github.com/yinglj","@type":"Person","name":"yinglj"},"datePublished":"2025-06-11T12:27:02.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/936/python-sdk/issues/936"}