docs(mcp): architecture doc and end-to-end capstone test for the aggregate gateway DCR flow

[tin-berri]

Relevant issues

Stacked on #33192 (grid interlude) -> #33191 -> #33190 -> #33189 -> #33188 -> #33182 -> #33174. The base of this PR is litellm_lit3637_grid_interlude; review and merge after those. This is the final PR of the LIT-3637 stack

Linear ticket

Resolves LIT-3637

Pre-Submission checklist

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

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

The capstone test chains the producer into the consumer on one shared master key: it drives the flow's own token endpoint to mint a session access_token, then presents that exact token to the aggregate /mcp admission (process_mcp_request) and asserts it admits as the signed-in user with the raw-key pipeline never touched

pytest tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py -q
21 passed

The full flow was also proven live end to end on a real proxy across the two PRs below this one (the register -> authorize -> complete -> token walk in #33189, and the session-bearer admission at /mcp in #33190)

Type

📖 Documentation

Changes

The final piece of the LIT-3637 stack: the architecture doc and the end-to-end capstone test. No production behavior changes here

GATEWAY_DCR.md documents the aggregate gateway DCR sign-in as a whole: what it is and how it relates to the dcr_bridge custody sibling, the mcp_gateway_dcr config, the seven-step flow (discovery, stateless registration, authorize with SSO interpose, the grid interlude, the deliberate complete step, token, and admission) with a sequence diagram, the security model for every client-held and sealed value, and where each piece lives. It lives next to the code, following the ARCHITECTURE.md precedent in the semantic-filter hook; the customer-facing Claude Desktop setup tutorial belongs in the litellm-docs site and is called out as such

The capstone test is the closest thing to an in-tree e2e for this feature. The stack's other tests exercise each module in isolation (the flow mints and validates codes and tokens; the admission arm admits tokens minted directly from the session module). This one closes the loop across the module boundary: a token that came out of aggregate_token is fed into process_mcp_request, so the producer and consumer cannot drift on key derivation, prefix, issuer, or claim shape without this test failing. A dedicated tests/e2e/mcp harness suite is not present on this branch, so this is scoped as an integration test in the existing tree rather than a new harness folder

QA runbook

Read GATEWAY_DCR.md and confirm the sequence matches the endpoints in gateway_dcr_flow.py and discoverable_endpoints.py. Run the flow test file and confirm the capstone passes. For the live walk, follow the QA runbooks in the two PRs below this one against a proxy with mcp_gateway_dcr: true

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

This is the final PR in the LIT-3637 stack, adding an architecture doc (GATEWAY_DCR.md) for the aggregate gateway DCR sign-in flow and a capstone integration test that closes the loop between the token producer (aggregate_token) and consumer (process_mcp_request). No production code is changed.

• GATEWAY_DCR.md documents the seven-step OAuth/DCR flow (discovery → registration → authorize → grid interlude → complete → token → admission), the security model for every client-held and sealed value, and where each piece lives in the codebase — however, the repository's rules require documentation to be placed in the litellm-docs repo rather than the main codebase.
• The capstone test (test_flow_minted_session_token_is_admissible_at_the_aggregate_edge) is entirely mock-based, makes no real network calls, and correctly asserts that a token minted by the flow's own token endpoint is admitted at the aggregate /mcp edge via the session bearer path (not the raw-key pipeline).

Confidence Score: 4/5

Safe to merge — no production code is changed; the only substantive question is whether the architecture doc belongs in this repo or in litellm-docs.

The capstone test is well-constructed and mock-safe. The sole concern is that GATEWAY_DCR.md is being committed to the main repo where the team's policy routes documentation to the litellm-docs site.

litellm/proxy/_experimental/mcp_server/GATEWAY_DCR.md — should this live in litellm-docs instead?

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/GATEWAY_DCR.md	New architecture doc for the aggregate gateway DCR sign-in flow; content is accurate and well-structured, but the repository's rules require documentation to live in the litellm-docs repo rather than the main codebase.
tests/test_litellm/proxy/_experimental/mcp_server/test_gateway_dcr_flow.py	Adds a capstone integration test that chains aggregate_token (producer) into MCPRequestHandler.process_mcp_request (consumer) on one shared master key; entirely mock-based with no real network calls, and the critical assertion (raw_key_pipeline.assert_not_called()) correctly validates the session bearer path.

_{Reviews (1): Last reviewed commit: "docs(mcp): architecture doc + producer-t..." | Re-trigger Greptile}

[greptile-apps]

Documentation belongs in the litellm-docs repo

This repository's rules block adding documentation here — it should live in the litellm-docs site instead. The PR description itself acknowledges the boundary ("The customer-facing tutorial … belongs in the litellm-docs site, not here"), but the same principle applies to architecture docs added under litellm/proxy/. The cited ARCHITECTURE.md precedent in the semantic-filter hook does not appear to exist in the repo, so that comparison cannot be verified.

Rule Used: Prevent documentation from being added - needs to ... (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!