docs(mcp,a2a): code-verified auth reference fixes + overview page

[michelligabriele]

Summary

A pass over the MCP and A2A gateway auth documentation, verified field-by-field against the current LiteLLM source. Closes several gaps in the dedicated pages, fixes a broken link to a missing #litellm-a2a-gateway anchor on the Bedrock AgentCore page, and adds a single new auth_overview.md page that side-by-sides MCP and A2A authn/authz so readers comparing the two surfaces don't have to stitch together four pages mentally.

Every config field, header name, default value, and error code in these changes was checked against the codebase before landing.

Changes

docs/mcp.md

• Extended the auth_type table from 5 to 9 values (none, oauth2, oauth2_token_exchange, token were missing); cross-linked the OAuth and OBO pages.
• Added a note that the header table describes the managed SSE/HTTP transport path — the OpenAPI-tool path emits Authorization: ApiKey <value> instead of X-API-Key for auth_type: api_key.

docs/mcp_oauth.md

• Extended the Config Reference table to cover oauth2_flow, authorization_url, registration_url, token_validation, token_storage_ttl_seconds (all present in examples elsewhere but never enumerated in the reference table).

docs/mcp_control.md

• New ## Permission Hierarchy section documenting the 5-level intersection (Key → Team → End-user → Agent → Org-as-ceiling) with a mermaid flowchart.
• New ## Per-entity Tool-Level Permissions section documenting object_permission.mcp_tool_permissions (per-key/team/agent dict, distinct from server-registration allowed_tools/disallowed_tools).

docs/mcp_public_internet.md

• New "Public Internet vs MCP Hub Visibility" section clarifying that available_on_public_internet (the IP-based filter, defaults to True) is independent of litellm.public_mcp_servers + litellm.public_mcp_hub_strict_whitelist (the GET /public/mcp_hub advertisement). Two mechanisms that are easy to conflate.

docs/a2a.md

• Expanded the Authentication section to mention x-litellm-api-key as the preferred header when the inbound Authorization carries a backend-bound token.
• New subsections: per-agent 403 RBAC; require_trace_id_on_calls_to_agent (returns 400, not 403) and its _by_agent sibling; sub-agent identity propagation — only X-LiteLLM-Trace-Id and X-LiteLLM-Agent-Id are forwarded downstream, not the caller's virtual key or end-user-id.

docs/a2a_agent_permissions.md

• New ## Agent Access Groups section documenting object_permission.agent_access_groups on a key/team (the field is exposed on LiteLLM_ObjectPermissionBase). Notes that tagging an agent with access groups is a dashboard-only operation today — POST /v1/agents does not expose agent_access_groups as a top-level field.

docs/providers/bedrock_agentcore.md

• New ## LiteLLM A2A Gateway section (fixes the broken #litellm-a2a-gateway anchor that docs/a2a.md linked to). Covers registration, dual outbound auth modes (Bearer/JWT short-circuit when litellm_params.api_key is set, SigV4 via base_aws_llm.get_credentials otherwise), the full 6-entry-point credential chain with EKS-relevant fields (aws_external_id, aws_web_identity_token, aws_profile_name, aws_sts_endpoint), and IRSA on EKS.

docs/auth_overview.md (new) + sidebars.js

• Single side-by-side reference for MCP and A2A: client→gateway auth (the MCP-ASGI-checks-only-2-of-6-headers gap is called out), backend auth (MCP's auth_type enum vs A2A's inferred-from-litellm_params mode), per-user passthrough conventions (MCP's first-dash-split vs A2A's exact-prefix-match), RBAC (MCP is 5-level, A2A is 2-level today), trace IDs + identity propagation, guardrails, and a copy-paste header cheatsheet. Mostly cross-links into the now-corrected dedicated pages.
• sidebars.js: adds auth_overview as the first item in the "Agent & MCP Gateway" category.

Test plan

• npm run build succeeds (verifies all internal cross-links resolve)
• npm run start and visually skim the new /docs/auth_overview page + each modified page
• Confirm the bedrock_agentcore#litellm-a2a-gateway anchor renders and resolves from docs/a2a.md
• Mermaid diagrams render in mcp_control.md and a2a_agent_permissions.md

Notes for reviewer

A code-review pass surfaced several errors in an earlier draft of this PR — most notably an inverted default for `available_on_public_internet` and an over-extrapolated 4-level A2A intersection model. Both were corrected in the final commit (`792edfd1`) before pushing. The commit message names it as a "fixup from code-review pass" so the history reflects the verification step.

One known open item that did NOT make this PR: `agent_access_groups` as a top-level field on `POST /v1/agents` — the field exists at the Prisma layer but is not exposed on `AgentConfig`. The docs note this and direct readers to the dashboard. Adding it to the Pydantic schema (and verifying end-to-end) is a separate code change.

(Supersedes the closed PR #155; commits rebased to attribute correctly.)

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	May 18, 2026 6:55pm