Expose session, auth, and transport information on handler Context

Problem

Users consistently need access to transport-level information from inside tool, resource, and prompt handlers. Today, this data exists in the system but is not accessible through the Context object that handlers receive.

There are three categories of information users are asking for:

Session identity

Users need to identify which client session they are serving — for per-session state, logging, debugging, or multi-tenant scenarios. The session ID exists at the transport layer (e.g., Mcp-Session-Id header for streamable HTTP, UUID query param for SSE) but there is no way to read it from a handler.

• #485 — "How to get session_id in tool"
• #942 — "How to expose mcp_session_id to user?"

Auth credentials

Users completing an OAuth flow need to access the authenticated token or claims inside their handlers. The auth middleware already validates tokens and stores them in a ContextVar (auth_context_var), but Context does not expose this.

• #638 — "FastMCP Auth Context in tools"

Transport metadata (HTTP headers, client info)

Users need access to HTTP request headers, client IP, or other request-level metadata. The Starlette Request object is passed through as ServerMessageMetadata.request_context and lands on ServerRequestContext.request, but it is typed as Any and not surfaced on Context.

• #750 — "How to get HTTP request headers in tools"
• #375 — "Passing client context to tools"

Current state

The underlying data is available in the system — it just is not reachable from Context:

• Session ID: managed by StreamableHTTPSessionManager / SseServerTransport, not exposed to handlers
• Auth info: stored in auth_context_var by AuthContextMiddleware, not exposed to handlers
• HTTP request: passed through as request_context: Any on ServerMessageMetadata, available on ServerRequestContext.request but not on Context

Scope

This issue is about designing and implementing access to these three categories of information on the handler Context. Key design considerations:

• Behavior varies by transport — stdio has no session ID, headers, or auth; stateless HTTP has no session ID; SSE has a different session ID mechanism than streamable HTTP
• The solution should work for both MCPServer (high-level) and low-level server handlers
• Should be consistent with the direction of #2021 (typed transport context) and #1684 (explicit context parameters)

Prior art

• PR #1608 — adds ctx.session_id by threading through InitializationOptions → ServerSession → RequestContext → Context

Related issues

• #2021 — Refactor handler context to be transport- and handler-type-aware (v2 architectural)
• #1684 — Refactor global contextvars into explicit parameters (v2 architectural)
• #2054 — Add dependency injection support to MCPServer (v2 architectural)

_{AI Disclaimer}

首先跟踪 Context、ServerRequestContext 和 ServerMessageMetadata.request_context，然后检查 StreamableHTTPSessionManager、SseServerTransport 和 AuthContextMiddleware。比较 #2021、#1684 和 #1608 中的实现方式。完成的标准是：在所有受支持的 transport 中，handlers 都能一致地访问适用的 session、身份验证和 transport 信息，包括文档中说明的数据不可用的情况。