Closes #26507.

Repro

LibreChat (and similar MCP clients that connect to multiple servers through one proxy) appends a per-tool unique-ID suffix to canonical tool names to disambiguate same-named tools across servers, e.g. fc_web_search-firecrawl_scrape_a1b2c3d4.

The semantic-tool-filter matcher currently only handles the symmetric prefix wrapping (opencode-style, litellm_<canonical>). Suffix-wrapped names fall through _name_matches_canonical, the filter ships tools: [] with tool_choice: "auto" to the upstream provider, and every strict OpenAI-compatible model returns 400 'tool_choice' is only allowed when 'tools' are specified.

m = SemanticMCPToolFilter._name_matches_canonical
m('litellm_fc_web_search-firecrawl_scrape', 'fc_web_search-firecrawl_scrape')  # True (existing)
m('fc_web_search-firecrawl_scrape_a1b2c3d4', 'fc_web_search-firecrawl_scrape')  # False (BUG)

Fix

Extend _name_matches_canonical to also accept client_name.startswith(canonical + sep) matches, while keeping the same anchoring guards as the suffix path:

1. Match must be adjacent to a separator character (_ or -); bare-substring matches do not count, so earthquake_alert does not match canonical ear.
2. canonical must contain MCP_TOOL_PREFIX_SEPARATOR, otherwise unrelated local user functions whose names share the same characters (e.g. firecrawl_scrape_v2_helper vs canonical firecrawl_scrape) would be spuriously selected. Symmetric with the suffix-direction guard added in fix(mcp_semantic_tool_filter): match tools with client-side namespace prefix (#26078) #26117.

The semantic delta is ~6 lines of logic and a refreshed docstring; the rest of the diff is reflowing introduced by the project's auto-formatter.

Test

Adds five regression tests:

• test_client_suffix_with_underscore_separator — exact shape from the bug report (<canonical>_<uid>)
• test_client_suffix_with_dash_separator — dash-separator variant
• test_prefix_without_separator_does_not_match — bare-substring guard in the prefix direction (earthquake_alert != ear)
• test_suffix_does_not_match_unprefixed_canonical — unprefixed-canonical guard in the prefix direction (mirror of fix(mcp_semantic_tool_filter): match tools with client-side namespace prefix (#26078) #26117's local-function guard)
• test_prefix_and_suffix_wrappers_can_coexist — mixed-client scenario

All 14 TestGetToolsByNames tests pass after the fix:

$ python -m pytest tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py::TestGetToolsByNames
14 passed in 12.49s

The new tests fail on the unpatched matcher (verified by reverting only the source change with git stash push <source-file> and re-running). All previous tests still pass.

🤖 Generated with Claude Code