Expose session, auth, and transport information on handler Context

[maxisbey]

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.

• How to get session_id in tool #485 — "How to get session_id in tool"
• How to expose mcp_session_id to user ? #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.

• FastMCP Auth Context in tools #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.

• how to get http request headers in mcp tools logic when i use streamable http mode to run mcp server ? #750 — "How to get HTTP request headers in tools"
• Passing client context to 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 Refactor handler context to be transport- and handler-type-aware #2021 (typed transport context) and Refactor global contextvars request context into explicit parameters #1684 (explicit context parameters)

Prior art

• PR feat: propagate session_id from transport to tool context #1608 — adds ctx.session_id by threading through InitializationOptions → ServerSession → RequestContext → Context

Related issues

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

_{AI Disclaimer}

[akshay-kumar-bm]

Hi @maxisbey — thanks for the detailed scoping. Wanted to ask before anyone starts work: how do you want this sequenced against #2021 (transport-aware context) and #1684 (replace contextvars)?

A naive implementation today that threads session_id, auth, and request onto Context via RequestContext (matching PR #1608's pattern for session_id) could end up rewritten when #1684 lands, so it'd help to know whether you'd prefer:

(a) Land #2098 first with explicit fields on Context, and let #1684 refactor the plumbing layer later, or

(b) Wait until #1684 / #2021 set the new contract for how transport-layer data reaches handlers, then add the three categories on top.

Happy to draft an API sketch for (a) if that's the preferred path. No claim either way — just trying to avoid duplicate or wasted work.