From 1cdb6cd3ac9cda2ccd0448c1300d315b8e708fa9 Mon Sep 17 00:00:00 2001 From: Krrish Dholakia Date: Mon, 22 Jun 2026 18:25:15 -0700 Subject: [PATCH] docs: add MCP server change guidelines (#31038) * docs: add MCP server change guidelines * Add outbound_credentials directory and update AGENTS.md Updated AGENTS.md to include new outbound_credentials directory and its files, along with additional comments on existing files. --------- Co-authored-by: tin-berri --- .../proxy/_experimental/mcp_server/AGENTS.md | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 litellm/proxy/_experimental/mcp_server/AGENTS.md diff --git a/litellm/proxy/_experimental/mcp_server/AGENTS.md b/litellm/proxy/_experimental/mcp_server/AGENTS.md new file mode 100644 index 00000000000..8eebc3ea3b3 --- /dev/null +++ b/litellm/proxy/_experimental/mcp_server/AGENTS.md @@ -0,0 +1,95 @@ +# Experimental MCP Server Change Guidelines + +Read @../../../../CLAUDE.md and @CLAUDE.md before changing this package. + +This directory owns the proxy-hosted MCP server implementation. Keep changes +inside the module that owns the behavior, and only reach outside this package +when the public type contract, database schema, dashboard, or cross-proxy route +wiring must change with it. + +## File Structure + +Respect the current package boundaries: + +```text +litellm/proxy/_experimental/mcp_server/ + AGENTS.md + CLAUDE.md + server.py # ASGI/MCP route handling, sessions, tool calls [PR7: 7-arm only — move BYOK/OAuth pre-fetch into resolver] + mcp_server_manager.py # upstream server registry, clients, tool routing [PR7: _create_mcp_client swaps resolve_mcp_auth -> resolve_credentials] + auth/ + user_api_key_auth_mcp.py # LiteLLM admission auth and MCP request headers + token_exchange.py # OAuth token exchange handling [unchanged; V1TokenExchangeAdapter delegates here] + litellm_auth_handler.py # authenticated-user adapter for MCP sessions + outbound_credentials/ # NEW — typed upstream-credential resolution (resolve_credentials + arms) + __init__.py # public surface: resolve_credentials, the configs, CredError + result.py # Ok | Error union (pure stdlib) + types.py # AuthConfig union, CredError, Subject, ServerSpec + httpx_auth.py # NoOpAuth, StaticHeaderAuth (every mode -> one httpx.Auth) + resolver.py # resolve_credentials(): exhaustive per-mode match + assert_never + seams.py # injected Protocols (one per cache-touching mode) + v1_adapters.py # v1-backed seam bodies; delegate to auth/oauth2/db owners + adapter.py # to_subject / to_server_spec / raise_public (v1 <-> v2 boundary) + discoverable_endpoints.py # MCP OAuth metadata, authorize, token, callback + byok_oauth_endpoints.py # BYOK OAuth UI/API flow + oauth_utils.py # redirect URI and proxy base URL validation + oauth2_token_cache.py # OAuth2 and per-user token resolution/cache [PR7: resolve_mcp_auth removed; cache class stays, V1OAuth2CacheAdapter delegates to async_get_token] + db.py # MCP server, credential, env var, submission DB access [unchanged; V1ByokStore delegates to _get_byok_credential / get_user_credential] + toolset_db.py # MCP toolset DB access + rest_endpoints.py # proxy REST facade for listing/calling MCP tools [PR7: 7-arm only — pass identity + inbound token down instead of mcp_auth_header] + openapi_to_mcp_generator.py# OpenAPI spec to MCP tool generation + sampling_handler.py # MCP sampling to LiteLLM completion flow + elicitation_handler.py # MCP elicitation relay flow + semantic_tool_filter.py # semantic filtering of available MCP tools + guardrail_translation/ + handler.py # MCP guardrail result translation + sse_transport.py # SSE transport implementation + mcp_context.py # contextvars for MCP request/session metadata + mcp_debug.py # debug helpers + tool_registry.py # in-memory MCP tool registry helpers + cost_calculator.py # MCP tool cost calculation + ui_session_utils.py # dashboard session auth context helpers + utils.py # shared primitives used by several modules +``` + +Do not add broad catch-all modules. Prefer the existing owner above, and add a +new file only for a distinct capability that would otherwise make an existing +module materially harder to understand. + +## Implementation Rules + +- Preserve the boundary between LiteLLM admission auth and upstream MCP auth. + Admission belongs in `auth/user_api_key_auth_mcp.py`; upstream token exchange, + delegated auth, per-user OAuth, BYOK, and raw header forwarding belong in the + dedicated OAuth/header modules. +- Treat `none`, bearer/API key, OAuth, OAuth token exchange, delegated upstream + auth, SSE, streamable HTTP, and stdio as separate flows. Do not collapse them + behind a single generic branch unless tests prove every mode still behaves + correctly. +- Be especially careful with `available_on_public_internet: false` combined with + `delegate_auth_to_upstream: true`. The local `CLAUDE.md` explains the anonymous + upstream PKCE path that must remain intentional. +- Keep database-backed fields in sync across migrations, typed models under + `litellm/types/mcp.py` or `litellm/types/mcp_server/`, config loading, this + package, and dashboard state when the field is user-visible. +- Use the official MCP SDK types and established LiteLLM Pydantic models where + they exist. Avoid untyped protocol dictionaries at package boundaries. +- Keep security-sensitive logic easy to audit. Header forwarding, IP filtering, + public internet checks, token storage, env var interpolation, and credential + encryption need focused tests for both allowed and rejected paths. +- Avoid adding comments to new code unless they explain non-obvious security or + protocol behavior. Prefer clear names and small functions. + +## Tests + +Mirror this package under `tests/test_litellm/proxy/_experimental/mcp_server/`. +For regressions, extend the existing mapped test file instead of creating a new +one. Use subdirectories that match the implementation path, such as +`auth/test_token_exchange.py` for `auth/token_exchange.py` and +`guardrail_translation/test_mcp_guardrail_handler.py` for +`guardrail_translation/handler.py`. + +Use `tests/mcp_tests/` only when extending an existing broader MCP integration +scenario that already lives there. Route, auth, tool listing, tool execution, +OAuth, sampling, elicitation, DB, and dashboard-session changes should have +focused coverage in the mirrored `tests/test_litellm/...` path first.