Parameterized Context loses request state in resource and prompt handlers

[morluto]

Description

A resource-template or prompt handler annotated with a parameterized Context[LifespanContextT] receives a different Context object from the one the server injected. The reconstructed object has none of the private request state, so accessing ctx.request_context, ctx.session, ctx.request_id, or lifespan state fails with:

ValueError: Context is not available outside of a request

The equivalent tool handler works, and handlers annotated with unparameterized Context happen to work. This makes the documented typed lifespan-context pattern unusable specifically in dynamic resources and prompts.

Minimal reproduction

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

import anyio
from mcp.client import Client
from mcp.server.mcpserver import Context, MCPServer


@asynccontextmanager
async def lifespan(_: MCPServer[str]) -> AsyncIterator[str]:
    yield "live-state"


async def main() -> None:
    server = MCPServer("probe", lifespan=lifespan)

    @server.resource("probe://{name}")
    async def resource(name: str, ctx: Context[str]) -> str:
        return f"{name}:{ctx.request_context.lifespan_context}"

    @server.prompt("probe")
    async def prompt(name: str, ctx: Context[str]) -> str:
        return f"{name}:{ctx.request_context.lifespan_context}"

    async with Client(server) as client:
        await client.read_resource("probe://value")
        await client.get_prompt("probe", {"name": "value"})


anyio.run(main)

Both calls fail. Each should return content containing value:live-state.

Root cause

ResourceTemplate.from_function and Prompt.from_function correctly omit the detected context parameter from their public argument schemas, but then wrap the original handler with pydantic.validate_call. At invocation time they inject the live Context into the wrapped handler, so Pydantic validates it again.

For a generic annotation, Pydantic converts the unparameterized runtime instance into Context[str, Any]. That creates a new model instance and does not carry over Context's private _request_context, _mcp_server, and related attributes:

server-created Context
        |
        v
validate_call parameter: Context[str]
        |
        v
new Context[str, Any] instance
        |
        v
private request state absent

A direct identity probe on current main shows:

Context       -> same object, request state present
Context[str]  -> new object, request state absent

Tools avoid this because FuncMetadata.call_fn_with_arg_validation validates only client-supplied arguments and passes injected values directly to the raw handler.

Impact

This affects resource templates and prompts that use typed lifespan context, including otherwise valid code following the SDK's generic Context[LifespanContextT] typing. It can also hide in tests that only assert that ctx is non-null rather than reading request-scoped state.

A compatible fix should preserve the existing validation/coercion of client-supplied resource or prompt arguments while passing the server-created context object directly, with its identity and private state intact.

Environment

• MCP Python SDK: 2.0.0 and current main at a4f4ccd091138771535e17191123f20b30fda68e
• Python: 3.12.13
• Pydantic: 2.12.5

AI assistance was used to investigate and draft this report.

[morluto]

Additional source context: current main already records this as a known limitation in docs/handlers/lifespan.md and docs/migration.md, and tests/docs_src/test_lifespan.py currently asserts that parameterized contexts fail for resources and prompts. I had missed that documentation when filing the initial report; it confirms the behavior is known, although I could not find a live tracking issue or PR.

I have a focused local fix ready that keeps pydantic.validate_call semantics for caller-supplied arguments but marks only the SDK-injected context parameter as SkipValidation. This preserves the original context object, sync/async handlers, argument coercion, and resource handlers using **kwargs.