test(mcp): add e2e test for stateless StreamableHTTP behavior

[michelligabriele]

Adds TestProxyMcpStatelessBehavior to test_proxy_mcp_e2e.py with a test that verifies two independent MCP clients can connect, initialize, and call tools without sharing session state. This catches the regression from PR #19809 where stateless=False broke clients that don't manage mcp-session-id headers.

Regression test for #20242

Relevant issues

Fixes #20242

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

✅ Test

Changes

• Added TestProxyMcpStatelessBehavior class to tests/mcp_tests/test_proxy_mcp_e2e.py
• test_independent_clients_no_shared_session: Two sequential independent MCP clients connect, initialize, list tools, and call tools without sharing any session state. Client A completes and disconnects, then Client B connects fresh — proving stateless mode works correctly.
• Uses the existing e2e infrastructure (real MCP math server + LiteLLM proxy) — no new dependencies or config needed.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 24, 2026 7:43pm

[greptile-apps]

Greptile Summary

Adds an end-to-end regression test (TestProxyMcpStatelessBehavior) to tests/mcp_tests/test_proxy_mcp_e2e.py that verifies two independent MCP clients can sequentially connect, initialize, and call tools without sharing session state. This is an e2e complement to the existing unit test test_streamable_http_session_manager_is_stateless in tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py, both targeting the regression from PR #19809 where stateless=False broke clients that don't manage mcp-session-id headers.

• New test_independent_clients_no_shared_session test creates Client A that connects, calls add(10, 20), and disconnects, then Client B connects fresh and calls add(100, 200) — proving stateless mode works correctly
• Uses existing e2e infrastructure (real MCP math server + LiteLLM proxy) with no new dependencies
• Follows the same patterns as existing tests in the file (fixtures, asyncio.timeout, assertion style)
• Note: The PR checklist claims tests were added in tests/litellm/, but the change is in tests/mcp_tests/. A corresponding unit test already exists in tests/test_litellm/ for the same issue.

Confidence Score: 5/5

• This PR is safe to merge — it adds only a test with no production code changes.
• This is a test-only PR that adds a single well-structured e2e test to an existing test file. It introduces no production code changes, no new dependencies, and follows the established patterns in the test suite. The test logic is straightforward and correct — it sequentially creates two independent clients to verify stateless behavior. The assertions are clear and match the expected math server outputs.
• No files require special attention.

Important Files Changed

Filename	Overview
tests/mcp_tests/test_proxy_mcp_e2e.py	Adds TestProxyMcpStatelessBehavior class with a single e2e test that verifies two independent MCP clients can connect sequentially without sharing session state. Well-structured, follows existing patterns, no issues found.

Sequence Diagram

sequenceDiagram
    participant Test as Test Runner
    participant CA as Client A
    participant Proxy as LiteLLM Proxy (stateless)
    participant MCP as MCP Math Server (stdio)
    participant CB as Client B

    Test->>CA: Create Client A
    CA->>Proxy: POST /mcp (initialize)
    Proxy->>MCP: Forward initialize
    MCP-->>Proxy: Initialized
    Proxy-->>CA: Initialized (no session ID required)

    CA->>Proxy: POST /mcp (call_tool: add(10,20))
    Proxy->>MCP: Forward call_tool
    MCP-->>Proxy: Result: 30
    Proxy-->>CA: Result: 30
    CA->>Test: Assert result == "30"
    Note over CA: Client A disconnects

    Test->>CB: Create Client B (fresh, no shared state)
    CB->>Proxy: POST /mcp (initialize)
    Proxy->>MCP: Forward initialize
    MCP-->>Proxy: Initialized
    Proxy-->>CB: Initialized (no session ID required)

    CB->>Proxy: POST /mcp (list_tools)
    Proxy->>MCP: Forward list_tools
    MCP-->>Proxy: Tools list
    Proxy-->>CB: Tools list (includes "add")

    CB->>Proxy: POST /mcp (call_tool: add(100,200))
    Proxy->>MCP: Forward call_tool
    MCP-->>Proxy: Result: 300
    Proxy-->>CB: Result: 300
    CB->>Test: Assert result == "300"

Loading

_{Last reviewed commit: 41af0e7}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[shin-bot-litellm]

Review

1. Does this PR fix the issue it describes?
Yes. Adds regression test for #20242 — verifies two independent MCP clients can connect without sharing session state.

2. Has this issue already been solved elsewhere?
The underlying bug (PR #19809 broke stateless mode) may already be fixed — this adds the regression test to prevent recurrence.

3. Are there other PRs addressing the same problem?
PR #22072 also touches MCP code — check for conflicts.

4. Are there other issues this potentially closes?
Directly addresses #20242 as a regression test.

✅ LGTM — test-only PR that adds valuable coverage for MCP stateless behavior.