[Feat] Make MCP timeouts configurable via environment variables

[shivamrawat1]

Relevant issues

MCP timeouts were hardcoded and could not be adjusted for slower or custom MCP servers. This change adds four environment variables so all MCP-related timeouts can be configured:
LITELLM_MCP_CLIENT_TIMEOUT (default 60s) – connection timeout for stdio and HTTP/SSE transports
LITELLM_MCP_TOOL_LISTING_TIMEOUT (default 30s) – timeout when listing tools for an MCP server
LITELLM_MCP_METADATA_TIMEOUT (default 10s) – HTTP timeout for OAuth metadata fetching
LITELLM_MCP_HEALTH_CHECK_TIMEOUT (default 10s) – timeout for MCP server health checks
These are read from litellm.constants and used in MCPClient and mcp_server_manager.py.

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature
📖 Documentation
✅ Test

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 27, 2026 1:18pm

[greptile-apps]

Greptile Summary

This PR makes all four MCP-related timeouts configurable via environment variables instead of being hardcoded. It introduces LITELLM_MCP_CLIENT_TIMEOUT (default 60s), LITELLM_MCP_TOOL_LISTING_TIMEOUT (default 30s), LITELLM_MCP_METADATA_TIMEOUT (default 10s), and LITELLM_MCP_HEALTH_CHECK_TIMEOUT (default 10s) as float constants in litellm/constants.py, and replaces all hardcoded timeout values in MCPClient and MCPServerManager.

• Adds 4 new configurable float constants to litellm/constants.py, following the existing pattern of float(os.getenv(...)).
• Changes MCPClient.__init__ timeout parameter default from 60.0 to None, falling back to MCP_CLIENT_TIMEOUT — preserves backward compatibility for callers passing explicit timeout values.
• Replaces all hardcoded timeouts in mcp_server_manager.py (60.0 for client, 30.0 for tool listing, 10.0 for metadata and health checks) with the corresponding constants.
• Includes mock-only unit tests in both tests/mcp_tests/ and tests/test_litellm/ verifying the env var override mechanism.
• Documentation updated in config_settings.md.

Confidence Score: 5/5

• This PR is safe to merge — it's a straightforward extraction of hardcoded values into configurable constants with no behavioral change at default values.
• All changes are mechanical replacements of hardcoded timeout literals with constants that have the same default values. Backward compatibility is preserved (explicit timeout parameters still override the constant). Tests verify the override mechanism. No new dependencies, no database changes, no critical path changes.
• No files require special attention.

Important Files Changed

Filename	Overview
litellm/constants.py	Adds 4 new float constants for MCP timeouts, each configurable via env var with sensible defaults. Follows existing patterns in the file.
litellm/experimental_mcp_client/client.py	Changes timeout parameter default from 60.0 to None, falling back to MCP_CLIENT_TIMEOUT constant. Maintains backward compatibility since explicit timeout values still take precedence.
litellm/proxy/_experimental/mcp_server/mcp_server_manager.py	Replaces all hardcoded timeout values (60.0, 30.0, 10.0) with corresponding constants from litellm.constants. Health check error message now uses the configurable timeout value.
tests/mcp_tests/test_mcp_client_unit.py	Adds a mock-only test verifying MCPClient uses the configurable MCP_CLIENT_TIMEOUT constant when no explicit timeout is passed.
tests/test_litellm/test_constants.py	Adds the 4 new MCP timeout constants to the env var name mapping so the existing generic override test covers them.
docs/my-website/docs/proxy/config_settings.md	Documents the 4 new environment variables for MCP timeouts with descriptions and defaults.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    ENV["Environment Variables\n(LITELLM_MCP_CLIENT_TIMEOUT,\nLITELLM_MCP_TOOL_LISTING_TIMEOUT,\nLITELLM_MCP_METADATA_TIMEOUT,\nLITELLM_MCP_HEALTH_CHECK_TIMEOUT)"]
    CONST["litellm/constants.py\n(MCP_CLIENT_TIMEOUT,\nMCP_TOOL_LISTING_TIMEOUT,\nMCP_METADATA_TIMEOUT,\nMCP_HEALTH_CHECK_TIMEOUT)"]
    CLIENT["MCPClient.__init__\ntimeout parameter"]
    MGR_CLIENT["MCPServerManager._create_mcp_client\nclient timeout"]
    MGR_TOOLS["MCPServerManager._fetch_tools_with_timeout\nanyio.fail_after"]
    MGR_META["MCPServerManager._fetch_oauth_metadata\nhttpx timeout"]
    MGR_HEALTH["MCPServerManager.health_check\nasyncio.wait_for timeout"]

    ENV -->|os.getenv| CONST
    CONST -->|MCP_CLIENT_TIMEOUT| CLIENT
    CONST -->|MCP_CLIENT_TIMEOUT| MGR_CLIENT
    CONST -->|MCP_TOOL_LISTING_TIMEOUT| MGR_TOOLS
    CONST -->|MCP_METADATA_TIMEOUT| MGR_META
    CONST -->|MCP_HEALTH_CHECK_TIMEOUT| MGR_HEALTH

Loading

_{Last reviewed commit: 420c12a}

[greptile-apps]

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}