fix(mcp): explain missing public client dependencies

[joshua-berri]

TLDR

Problem this solves:

• Missing MCP dependencies produce unhelpful import errors
• Custom HTTPX integrations need explicit migration boundaries

How it solves it:

• Recommend pip install 'litellm[mcp]' for missing MCP/HTTPX2
• Preserve original causes and unrelated import failures
• Document public imports and HTTPX2 integration requirements

User Flow

Before: a core-only LiteLLM installation cannot explain how to enable MCP

1. Install LiteLLM without extras
2. Run python -c "from litellm.experimental_mcp_client.client import MCPClient"
3. Observe ModuleNotFoundError: No module named 'mcp'

After: the same attempted import explains which extra to install

1. Install LiteLLM without extras
2. Run python -c "from litellm.experimental_mcp_client.client import MCPClient"
3. Observe an ImportError recommending pip install 'litellm[mcp]', with the original missing-module cause
4. Install the extra and use the existing client import and constructor

Relevant issues

Narrow follow-up to #41718, which already ported SDK2 transports, sessions, handlers, callbacks and results

Affected release

Linear ticket

Resolves LIT-7740

Pre-Submission checklist

• I have added meaningful tests
• The handful of test files covering my change pass locally
• My PR passes all required CI/CD checks
• My PR's scope is as isolated as possible
• I have received a Greptile Confidence Score of at least 4/5

Validation

The public-client test directory now runs once in the existing MCP shard. The misc shard references directories removed by the concurrent test migration and was collecting zero tests. Moving this directory restores actual regression execution and hosted coverage without changing the shared runner

The workflow ownership guard and its 34 tests pass. Pinned zizmor 1.24.1 reports no findings. Final source-built local core checks pass (8/8); the Python implementation is unchanged from the independent verification

The mapped regressions first failed on missing-MCP and missing-HTTPX2 guidance, while unrelated missing modules and incompatible SDK imports retained their original errors. All 216 affected client/helper tests pass at 671b51c9599bc84e679add55a3a6eb1775fa6b9c. Existing logging/result/alias/auth-header checks pass (60 tests), as do seven callback/error-handler checks. One pre-existing local-only external-service test remains skipped and is not counted as a pass

Local full production/test-tree Ruff, formatting, strict-rule, type-discipline, test-quality and canonical basedpyright budget gates pass, as do circular-import and import-safety checks. Changed production executable-line coverage is 6/6 (100%); the touched initializer's branches are 2/2 (100%). Hosted coverage is pending for the refreshed tip; the previous tip had complete uploads and 100% changed-line coverage

Independent Devin execution at 4fda0092d3 confirmed the source-built import fix, all eight core-wheel smoke checks, and all 216 mapped tests. Controlled HTTP/SSE/stdio calls returned 42 with is_error=False on both revisions. A supplemental controlled peer verified bearer authentication over HTTP and SSE on both revisions: missing/wrong credentials returned 401 without tool execution, while valid credentials returned 42. Legacy negotiation and modern-header rejection remain unchanged

Screenshots / Proof of Fix

Both revisions were built locally on macOS with uv build --wheel, then installed in turn using uv pip install --no-deps --reinstall --python local-core/bin/python <wheel>. The isolated environment already contained core dependencies. Each command ran outside the source checkout, importing the installed wheel; MCP and HTTPX2 were absent on both revisions

Before: 0f7d4dc13b493dd6bfe1d03346e309a6494b1711

1. Run local-core/bin/python -c 'import litellm': exit 0
2. Run local-core/bin/python -c 'from litellm.experimental_mcp_client.client import MCPClient': exit 1, ModuleNotFoundError: No module named 'mcp', without installation guidance

After: 671b51c9599bc84e679add55a3a6eb1775fa6b9c

1. Run local-core/bin/python -c 'import litellm': exit 0
2. Run local-core/bin/python -c 'from litellm.experimental_mcp_client.client import MCPClient': exit 1, ImportError: MCP client dependencies are missing. Install them with: pip install 'litellm[mcp]', with the original missing-module exception as its direct cause

Review status

At 671b51c9599bc84e679add55a3a6eb1775fa6b9c, local validation passes; hosted checks, Codecov and fresh bot reviews are pending. The previous OAuth run exited before executing tests because its workflow targeted a test file absent from the old PR checkout. Merging current main aligns the workflow and checkout, and all four OAuth cases now collect locally. Actual OAuth execution remains pending in CI

Contributor agreement status is not exposed by the PR checks and has not been independently confirmed

Type

Bug Fix
Documentation
Test

Caveats (if any)

Low

• Phase 0 release, canary and rollback gates remain separate
• Shared Python consumers must use SDK2 and HTTPX2

Final Attestation

• Tests cover missing extras and preserve unrelated import failures

---

Note

Low Risk
Changes are limited to import error messaging, documentation, CI test sharding, and tests; no runtime MCP client behavior changes in the diff.

Overview
Improves optional MCP client installs by turning missing mcp or httpx2 on litellm.experimental_mcp_client into an ImportError that recommends pip install 'litellm[mcp]', while leaving other missing modules and incompatible SDK import failures unchanged.

The MCP client readme now documents the public import path, the [mcp] extra, and that custom HTTP auth and client hooks must use httpx2 (no HTTPX1 shim). Base-wheel smoke checks assert that guidance on a core-only install, and unit tests cover the import edge cases.

CI runs tests/test_litellm/experimental_mcp_client in the mcp-integration shard instead of misc, so those regressions run with the MCP test environment.

^{Reviewed by Cursor Bugbot for commit 671b51c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[joshua-berri]

bugbot run. Please review this focused MCP import-error fix, including exception preservation, optional-dependency regression coverage, and the documented HTTPX2 compatibility boundaries.

[joshua-berri]

@veria-ai Please review this focused MCP import-error fix, including exception preservation, optional-dependency regression coverage, and the documented HTTPX2 compatibility boundaries.

[joshua-berri]

@greptileai Please review this focused MCP import-error fix, including exception preservation, optional-dependency regression coverage, and the documented HTTPX2 compatibility boundaries.

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_mcp_public_client_7740 (671b51c) with main (cbcccd5)¹}

Footnotes

1. No successful run was found on main (0f7d4dc) during the generation of this report, so cbcccd5 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding correctness, security, or repository-rule issues.

Summary

This PR improves errors when optional MCP client dependencies are absent and restores the client tests to an active CI shard.

• Converts missing mcp or httpx2 modules into actionable installation guidance while preserving the original exception as the cause.
• Preserves unrelated missing-module and incompatible-SDK errors unchanged.
• Documents the MCP extra and HTTPX2 integration boundary in the existing MCP README.
• Runs the public MCP client tests with the MCP integration shard instead of the obsolete misc-shard path.

_{Reviews (4) · Last reviewed commit: "chore: merge main for MCP OAuth CI compa..."}

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai Please reassess both findings using the supplied execution evidence and your README exemption. Neither finding requires a production change.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[joshua-berri]

@greptileai Please review d93cc8d: public-client regressions now run in the existing MCP shard, avoiding zero collection from migrated misc directories.

[joshua-berri]

bugbot run. Please review d93cc8d: public-client regressions now run in the existing MCP shard; the previously reviewed production code is unchanged.

[joshua-berri]

@veria-ai Please review d93cc8d: public-client regressions now run in the existing MCP shard; the previously reviewed production code is unchanged.

[cursor]

Stale Bugbot comment from a previous run.

[joshua-berri]

@greptileai Please review 671b51c after merging main to align the OAuth workflow and test checkout; local validation passes

[joshua-berri]

bugbot run. Please review 671b51c after merging main to align the OAuth workflow and test checkout; local validation passes

[joshua-berri]

@veria-ai Please review 671b51c after merging main to align the OAuth workflow and test checkout; local validation passes

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 671b51c. Configure here.}