agentenv-framework-protocol 0.1.325__tar.gz → 0.1.326__tar.gz

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.325
+Version: 0.1.326
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -35,6 +35,7 @@ Requires-Dist: regex>=2023.12.25; extra == 'agent'
 Requires-Dist: uvicorn>=0.30; extra == 'agent'
 Provides-Extra: dev
 Requires-Dist: a2a-sdk[http-server]<0.4,>=0.3.26; extra == 'dev'
+Requires-Dist: fastmcp<4,>=3.4; extra == 'dev'
 Requires-Dist: mcp<2,>=1.25; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=9.0; extra == 'dev'
@@ -213,6 +214,8 @@ extension's, and `client.invoke_extension(base_url, card, uri, params, method=..
 its HTTP verb. Without `method`, `invoke_extension` calls the first method listed; an extension
 with several methods, such as a gateway's `urn:agentenv:clock/v1`, should always be called by name.
 
+Where the binding lives depends on the app. On mcp's own FastMCP it wraps the tool manager's dispatch; on the standalone `fastmcp` package it joins the app's middleware chain as the outermost layer, so a handler's own middleware runs under it too. An app with neither seam mounts unbound, with a warning, unless a tool declares a `ToolContext` parameter or the handler defines `on_tool_call`: then the mount is refused rather than serving an empty caller.
+
 ### Uploading an export through a grant
 
 An export too large to return from `data/get` can go straight to the caller's object store. A

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/README.md

@@ -169,6 +169,8 @@ extension's, and `client.invoke_extension(base_url, card, uri, params, method=..
 its HTTP verb. Without `method`, `invoke_extension` calls the first method listed; an extension
 with several methods, such as a gateway's `urn:agentenv:clock/v1`, should always be called by name.
 
+Where the binding lives depends on the app. On mcp's own FastMCP it wraps the tool manager's dispatch; on the standalone `fastmcp` package it joins the app's middleware chain as the outermost layer, so a handler's own middleware runs under it too. An app with neither seam mounts unbound, with a warning, unless a tool declares a `ToolContext` parameter or the handler defines `on_tool_call`: then the mount is refused rather than serving an empty caller.
+
 ### Uploading an export through a grant
 
 An export too large to return from `data/get` can go straight to the caller's object store. A

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.325"
+version = "0.1.326"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,6 +41,7 @@ dev = [
     "pytest>=9.0",
     "pytest-asyncio>=0.23.0",
     "mcp>=1.25,<2",
+    "fastmcp>=3.4,<4",  # the standalone-fastmcp mount path
 ]
 [project.urls]
 Homepage = "https://www.agentenvframework.com"

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/src/agentenv_protocol/agent_env_environment.py

@@ -217,6 +217,10 @@ class AgentEnvApplication(ABC):
 class AgentEnvFastMCPApplication(AgentEnvApplication):
     supports_tools: ClassVar[bool] = True
     _hook: Callable | None = None
+    #: How this app's tool calls get their ToolContext, decided by ``_check_tool_binding``: ``"dispatch"`` wraps
+    #: mcp FastMCP's tool manager, ``"middleware"`` joins a fastmcp app's middleware chain, None leaves them unbound.
+    _binding: str | None = None
+    _middleware: Any = None
 
     def _add_route(self, app: Any, path: str, methods: list, handler: Callable) -> None:
         app.custom_route(path, methods=methods)(handler)
@@ -225,23 +229,53 @@ class AgentEnvFastMCPApplication(AgentEnvApplication):
         app.tool(name=descriptor.name, description=descriptor.description)(injecting(fn))
 
     def _check_tool_binding(self, app: Any) -> None:
-        """Refuse before any route or tool is added: an app without the dispatch the binding wraps (its tool
-        calls would run unbound, which nothing reading ``ToolContext.current()`` can tell from an empty
-        caller), a dispatch this protocol already wraps (one handler per app, or the second hook would answer
-        the first handler's tools) and an ``on_tool_call`` of the wrong shape. The hook is kept for
-        ``_bind_tool_calls``."""
+        """Decide, before any route or tool is added, how every tools/call on ``app`` gets its ToolContext, and
+        refuse what cannot be honoured. The standalone ``fastmcp`` package (a ``middleware`` list with
+        ``add_middleware``) is joined through that public chain, checked first because its 2.x line also keeps a
+        tool manager whose dispatch has another shape; mcp's own FastMCP (``mcp>=1.25,<2``) has no public hook,
+        so its tool manager's ``call_tool`` is wrapped. An app with neither cannot bind: mounting it is refused
+        when the handler declared that it reads the context (a ``ToolContext`` parameter or an ``on_tool_call``),
+        since an empty caller would then be a lie nothing can detect, and goes ahead unbound, with a warning,
+        otherwise. A dispatch this protocol already wraps is refused either way (one handler per app, or the
+        second hook would answer the first handler's tools), an ``on_tool_call`` of the wrong shape fails here,
+        not per call, and so does a fastmcp that cannot be imported: nothing has been added to the app yet."""
+        self._hook = _tool_call_hook(self.handler)
+        middleware = getattr(app, "middleware", None)
+        if isinstance(middleware, list) and callable(getattr(app, "add_middleware", None)):
+            if any(getattr(entry, _TOOL_CONTEXT_BOUND_ATTR, False) for entry in middleware):
+                raise RuntimeError("this fastmcp app already carries an AgentEnv tool-context middleware; mount one handler per app")
+            self._middleware = _tool_context_middleware(self._hook)
+            self._binding = "middleware"
+            return
         manager = getattr(app, "_tool_manager", None)
-        if not (callable(getattr(manager, "call_tool", None)) and callable(getattr(manager, "get_tool", None))):
+        if callable(getattr(manager, "call_tool", None)) and callable(getattr(manager, "get_tool", None)):
+            if getattr(manager.call_tool, _TOOL_CONTEXT_BOUND_ATTR, False):
+                raise RuntimeError("this FastMCP app already carries an AgentEnv tool dispatch; mount one handler per app")
+            self._binding = "dispatch"
+            return
+        readers = [descriptor.name for descriptor, fn in self._tools if _tool_context_slot(fn)]
+        if readers or self._hook is not None:
             raise RuntimeError(
-                "this app has no FastMCP tool dispatch to bind a ToolContext around "
-                "(mcp>=1.25,<2 keeps it at FastMCP._tool_manager); "
-                "an app that serves no tools mounts through AgentEnvStarletteApplication"
+                "this app has no tool dispatch to bind a ToolContext around (mcp>=1.25,<2 keeps one at "
+                f"FastMCP._tool_manager; fastmcp exposes a middleware list), and {', '.join(readers) or 'on_tool_call'} "
+                "would read an empty caller"
             )
-        if getattr(manager.call_tool, _TOOL_CONTEXT_BOUND_ATTR, False):
-            raise RuntimeError("this FastMCP app already carries an AgentEnv tool dispatch; mount one handler per app")
-        self._hook = _tool_call_hook(self.handler)
+        self._binding = None
+        logger.warning(
+            "%s.%s (environment %r): no tool dispatch to bind a ToolContext around, so its tool calls run with an "
+            "empty caller; build the app with create_fastmcp_app or on fastmcp to bind one",
+            type(app).__module__, type(app).__qualname__, self.environment_card.name,
+        )
 
     def _bind_tool_calls(self, app: Any) -> None:
+        """Bind as ``_check_tool_binding`` decided. First in fastmcp's middleware list runs outermost, so a
+        handler's own middleware and the tool both run under the binding, the same layering as the wrap."""
+        if self._binding == "dispatch":
+            self._bind_tool_dispatch(app)
+        elif self._binding == "middleware":
+            app.middleware.insert(0, self._middleware)
+
+    def _bind_tool_dispatch(self, app: Any) -> None:
         """Wrap the tool manager's ``call_tool``, which every tools/call resolves at call time, so each call
         of a registered tool runs under its ToolContext and the handler's ``on_tool_call`` may answer
         it first. An unknown tool name goes straight to the dispatch, whose error answers it. FastMCP
@@ -337,9 +371,10 @@ class AgentEnvEnvironment:
         """Runs before every tools/call on this environment's app, under the bound ``context``.
 
         Return None to let the call proceed, or an ``mcp.types.CallToolResult`` (``isError=True`` for
-        a refusal) to answer the call without running the tool; it reaches the wire verbatim, before
-        output validation. Anything else raises TypeError. May be ``async``. Not invoked for
-        extension (REST) routes.
+        a refusal) to answer the call without running the tool. On mcp's FastMCP it reaches the wire
+        verbatim, before output validation; on a fastmcp app it passes through fastmcp's output validation,
+        so a non-error answer there must fit the tool's declared output, while a refusal passes unchanged.
+        Anything else raises TypeError. May be ``async``. Not invoked for extension (REST) routes.
         """
         return None
 
@@ -556,6 +591,47 @@ def _check_call_tool_result(value: Any) -> None:
         raise TypeError(f"on_tool_call must return None or mcp.types.CallToolResult, got {type(value).__name__}")
 
 
+def _tool_context_middleware(hook: Callable | None) -> Any:
+    """A fastmcp ``Middleware`` that runs every tools/call under its ToolContext, the handler's ``on_tool_call``
+    first. A ``Middleware`` subclass rather than a bare ``(context, call_next)`` callable because fastmcp runs the
+    typed ``on_call_tool`` exactly once per call, where a bare callable runs once per dispatch phase. fastmcp is
+    not a dependency of this package: it is imported here, where an app built with it has just been handed over."""
+    try:
+        from fastmcp.server.middleware import Middleware
+    except ImportError as e:
+        raise RuntimeError("this app carries a fastmcp middleware list but fastmcp cannot be imported") from e
+
+    class ToolContextMiddleware(Middleware):
+        async def on_call_tool(self, context: Any, call_next: Callable) -> Any:
+            message = context.message
+            arguments = dict(getattr(message, "arguments", None) or {})
+            with bound(context_from_mcp(context.fastmcp_context, message.name, arguments)) as tool_context:
+                if hook is not None:
+                    answer = await _maybe_await(hook(tool_context))
+                    if answer is not None:
+                        _check_call_tool_result(answer)
+                        return _fastmcp_tool_result(answer)
+                return await call_next(context)
+
+    middleware = ToolContextMiddleware()
+    setattr(middleware, _TOOL_CONTEXT_BOUND_ATTR, True)
+    return middleware
+
+
+def _fastmcp_tool_result(answer: Any) -> Any:
+    """A hook's ``mcp.types.CallToolResult`` as the ``ToolResult`` a fastmcp middleware chain returns, the error
+    flag kept, under the field spellings of mcp 1 and 2."""
+    from fastmcp.tools import ToolResult
+    # mcp 2's spellings first: on mcp 1 they are plain misses, on mcp 2 the camel-case ones are deprecation shims.
+    structured = getattr(answer, "structured_content", None)
+    if structured is None:
+        structured = getattr(answer, "structuredContent", None)
+    is_error = getattr(answer, "is_error", None)
+    if is_error is None:
+        is_error = getattr(answer, "isError", False)
+    return ToolResult(content=list(answer.content), structured_content=structured, is_error=bool(is_error))
+
+
 def _schema_from_signature(fn: Callable) -> dict:
     """Derive a JSON-Schema object for a handler's call params from its signature (Annotated[Field] descriptions
     included). Injected parameters (``ToolContext``, FastMCP ``Context``) are not wire parameters and are left out."""

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/src/agentenv_protocol/tool_context.py

@@ -185,14 +185,24 @@ def context_from_mcp(context: Any, tool: str, arguments: Mapping[str, Any]) -> T
             request_context = context.request_context
         except (ValueError, AttributeError):
             request_context = None
-    meta = getattr(request_context, "meta", None)
-    extra = getattr(meta, "model_extra", None) if meta is not None else None
+    extra = _meta_entries(getattr(request_context, "meta", None))
     request = getattr(request_context, "request", None)
     headers = getattr(request, "headers", None) if request is not None else None
     return ToolContext(caller=caller_from_request(extra, headers), tool=tool, arguments=_frozen(arguments),
                        call_id=uuid.uuid4().hex)
 
 
+def _meta_entries(meta: Any) -> Optional[Mapping[str, Any]]:
+    """A request's custom ``_meta`` entries: pydantic's ``model_extra`` where the SDK models them (mcp 1), the
+    mapping itself where it hands them over as a dict (mcp 2)."""
+    if meta is None:
+        return None
+    extra = getattr(meta, "model_extra", None)
+    if extra is not None:
+        return extra
+    return meta if isinstance(meta, Mapping) else None
+
+
 def context_from_http(request: Any, tool: str, arguments: Mapping[str, Any]) -> ToolContext:
     """The context for a REST or extension call: the caller from the request headers only."""
     headers = getattr(request, "headers", None) if request is not None else None

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/tests/test_tool_context.py

@@ -286,7 +286,7 @@ def test_injecting_raises_when_a_slotted_function_has_unresolvable_annotations()
 def test_target_without_a_tool_dispatch_is_refused_before_any_route_is_added(strip):
     mcp = _FakeMCP()
     strip(mcp)
-    with pytest.raises(RuntimeError, match="no FastMCP tool dispatch"):
+    with pytest.raises(RuntimeError, match="no tool dispatch .* whoami, whoami_sync would read an empty caller"):
         AgentEnvFastMCPApplication(environment_card=EnvironmentCard(name="items"), handler=_SlotHandler()).add_routes_to_app(mcp)
     assert mcp.routes == [] and mcp.tools == {}
 

agentenv_framework_protocol-0.1.326/tests/test_tool_context_fastmcp.py

@@ -0,0 +1,224 @@
+"""ToolContext on the standalone ``fastmcp`` package, the way a plugin mounts it: no ``_tool_manager`` seam, so the
+protocol joins the app's middleware chain, outermost. The hook, both role sources, the per-call reset and the
+one-handler-per-app refusal hold as on mcp's FastMCP; an app with neither seam mounts unbound unless a reader is
+declared."""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import anyio
+import httpx
+import pytest
+
+fastmcp = pytest.importorskip("fastmcp")
+from fastmcp import Client, FastMCP  # noqa: E402
+from fastmcp.exceptions import ToolError  # noqa: E402
+from fastmcp.server.middleware import Middleware  # noqa: E402
+from mcp import ClientSession  # noqa: E402
+from mcp.client import streamable_http as _streamable_http  # noqa: E402
+from mcp.types import CallToolResult, TextContent  # noqa: E402
+
+from agentenv_protocol import (  # noqa: E402
+    ROLE_HEADER,
+    ROLE_META_KEY,
+    AgentEnvEnvironment,
+    AgentEnvFastMCPApplication,
+    Caller,
+    EnvironmentCard,
+    ToolContext,
+    environment_card,
+    tool,
+)
+from agentenv_protocol.agent_env_environment import _TOOL_CONTEXT_BOUND_ATTR  # noqa: E402
+from agentenv_protocol.tool_context import EMPTY  # noqa: E402
+
+
+class _Budget(Middleware):
+    """A handler's own middleware, as a plugin installs one: records the caller it sees, refuses past a budget."""
+
+    def __init__(self, budget: int = 100) -> None:
+        self.seen: list = []
+        self.budget = budget
+
+    async def on_call_tool(self, context, call_next):
+        self.seen.append(ToolContext.current().caller.role)
+        if len(self.seen) > self.budget:
+            raise ToolError("budget spent")
+        return await call_next(context)
+
+
+@environment_card(name="fm")
+class _Env(AgentEnvEnvironment):
+    def __init__(self) -> None:
+        self.hook_roles: list = []
+        self.seen: list = []
+
+    def on_tool_call(self, context: ToolContext):
+        self.hook_roles.append(context.caller.role)
+        if context.caller.role == "intruder":
+            return CallToolResult(isError=True, content=[TextContent(type="text", text="refused: intruder")])
+        return None
+
+    @tool()
+    def whoami_sync(self, ctx: ToolContext) -> str:
+        self.seen.append(ctx)
+        return f"{ctx.caller.role or '-'}|{ToolContext.current().caller.role or '-'}"
+
+    @tool()
+    async def whoami_async(self) -> str:
+        await asyncio.sleep(0)
+        self.seen.append(ToolContext.current())
+        return ToolContext.current().caller.role or "-"
+
+
+@environment_card(name="plain")
+class _PlainEnv(AgentEnvEnvironment):
+    @tool()
+    def echo(self, q: str) -> str:
+        return q
+
+
+@environment_card(name="reader")
+class _ReaderEnv(AgentEnvEnvironment):
+    @tool()
+    def whoami(self, ctx: ToolContext) -> str:
+        return ctx.caller.role or "-"
+
+
+@environment_card(name="hooked")
+class _HookedEnv(_PlainEnv):
+    def on_tool_call(self, context: ToolContext):
+        return None
+
+
+class _NoSeamApp:
+    """An app with the generic surfaces only: no tool manager, no middleware list."""
+
+    def __init__(self) -> None:
+        self.routes: list = []
+        self.tools: dict = {}
+
+    def custom_route(self, path, methods):
+        def register(fn):
+            self.routes.append((path, tuple(methods), fn))
+            return fn
+        return register
+
+    def tool(self, name, description):
+        def register(fn):
+            self.tools[name] = fn
+            return fn
+        return register
+
+
+class _ForeignListApp(_NoSeamApp):
+    """Not fastmcp: a ``middleware`` list without ``add_middleware`` is somebody else's list."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.middleware: list = []
+
+
+def _text(result) -> str:
+    return result.content[0].text
+
+
+def _is_error(result) -> bool:
+    return bool(getattr(result, "is_error", getattr(result, "isError", False)))
+
+
+@pytest.mark.asyncio
+async def test_mount_joins_the_middleware_chain_outermost_and_binds_every_call():
+    budget = _Budget()
+    app = FastMCP("fm", middleware=[budget])
+    env = _Env()
+    env.mount(app)
+    assert getattr(app.middleware[0], _TOOL_CONTEXT_BOUND_ATTR, False) is True and app.middleware[1] is budget
+    with anyio.fail_after(30):
+        async with Client(app) as client:
+            alice = await client.call_tool("whoami_sync", {}, meta={ROLE_META_KEY: "alice"})
+            bob = await client.call_tool("whoami_async", {}, meta={ROLE_META_KEY: "bob"})
+            nobody = await client.call_tool("whoami_sync", {})
+            blank = await client.call_tool("whoami_async", {}, meta={ROLE_META_KEY: "default"})
+    assert (_text(alice), _text(bob), _text(nobody), _text(blank)) == ("alice|alice", "bob", "-|-", "-")
+    assert budget.seen == ["alice", "bob", None, None], "the handler's own middleware runs under the binding"
+    assert env.hook_roles == ["alice", "bob", None, None]
+    assert [c.tool for c in env.seen] == ["whoami_sync", "whoami_async", "whoami_sync", "whoami_async"]
+    assert env.seen[0].arguments == {} and env.seen[0].call_id
+    assert ToolContext.current() is EMPTY
+
+
+@pytest.mark.asyncio
+async def test_the_hook_answers_a_call_before_the_tool_runs():
+    app = FastMCP("fm")
+    env = _Env()
+    env.mount(app)
+    with anyio.fail_after(30):
+        async with Client(app) as client:
+            refused = await client.call_tool("whoami_sync", {}, meta={ROLE_META_KEY: "intruder"}, raise_on_error=False)
+            served = await client.call_tool("whoami_sync", {}, meta={ROLE_META_KEY: "carol"})
+    assert _is_error(refused) and _text(refused) == "refused: intruder"
+    assert [c.caller.role for c in env.seen] == ["carol"], "the refused call never reached the tool"
+    assert _text(served) == "carol|carol"
+    assert env.hook_roles == ["intruder", "carol"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(not hasattr(_streamable_http, "streamable_http_client"), reason="mcp without streamable_http_client")
+async def test_a_direct_caller_over_http_gets_the_header_role_and_its_own_session():
+    app = FastMCP("fm")
+    env = _Env()
+    env.mount(app)
+    asgi = app.http_app(path="/mcp", json_response=True)
+    base = "http://127.0.0.1:8000"
+    client = httpx.AsyncClient(transport=httpx.ASGITransport(app=asgi), base_url=base, headers={ROLE_HEADER: "grader"})
+    with anyio.fail_after(30):
+        async with asgi.router.lifespan_context(asgi), client:
+            async with _streamable_http.streamable_http_client(f"{base}/mcp", http_client=client) as (read, write, session_id):
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    direct = await session.call_tool("whoami_sync", {})
+                    proxied = await session.call_tool("whoami_sync", {}, meta={ROLE_META_KEY: "bob"})
+                    sid = session_id()
+    assert sid and direct.content[0].text == "grader|grader" and proxied.content[0].text == "bob|bob"
+    assert env.seen[-2].caller == Caller("grader", sid)
+    assert env.seen[-1].caller == Caller("bob")  # a _meta role entry: the connection's id is not the caller's
+
+
+@pytest.mark.asyncio
+async def test_concurrent_callers_keep_their_own_context():
+    app = FastMCP("fm")
+    env = _Env()
+    env.mount(app)
+    roles = [f"agent-{i}" for i in range(24)]
+    with anyio.fail_after(60):
+        async with Client(app) as client:
+            results = await asyncio.gather(
+                *(client.call_tool("whoami_async", {}, meta={ROLE_META_KEY: role}) for role in roles))
+    assert [_text(r) for r in results] == roles
+    assert sorted(env.hook_roles) == sorted(roles)
+    assert ToolContext.current() is EMPTY
+
+
+def test_one_handler_per_fastmcp_app():
+    app = FastMCP("fm")
+    _Env().mount(app)
+    with pytest.raises(RuntimeError, match="already carries"):
+        AgentEnvFastMCPApplication(EnvironmentCard(name="second"), _PlainEnv()).add_routes_to_app(app)
+    assert sum(1 for entry in app.middleware if getattr(entry, _TOOL_CONTEXT_BOUND_ATTR, False)) == 1
+
+
+def test_an_app_with_no_seam_mounts_unbound_unless_a_reader_is_declared(caplog):
+    app = _NoSeamApp()
+    with caplog.at_level(logging.WARNING, logger="agentenv_protocol.agent_env_environment"):
+        _PlainEnv().mount(app)
+    assert "echo" in app.tools and app.tools["echo"]("hi") == "hi"
+    assert "empty caller" in caplog.text
+    for env, reader in ((_ReaderEnv(), "whoami"), (_HookedEnv(), "on_tool_call")):
+        with pytest.raises(RuntimeError, match=reader):
+            env.mount(_NoSeamApp())
+    foreign = _ForeignListApp()
+    with pytest.raises(RuntimeError, match="whoami"):
+        _ReaderEnv().mount(foreign)
+    assert foreign.middleware == [] and foreign.tools == {}, "a foreign list is not a seam, and nothing was added"

{agentenv_framework_protocol-0.1.325 → agentenv_framework_protocol-0.1.326}/tests/test_tool_context_injection.py

@@ -38,7 +38,7 @@ from agentenv_protocol import (  # noqa: E402
     tool,
 )
 from agentenv_protocol.agent_env_environment import _is_fastmcp_context_annotation, _schema_from_signature  # noqa: E402
-from agentenv_protocol.tool_context import EMPTY, bound  # noqa: E402
+from agentenv_protocol.tool_context import EMPTY, bound, context_from_mcp  # noqa: E402
 
 
 def _text(result: Any) -> str:
@@ -174,6 +174,14 @@ async def test_concurrent_calls_with_different_meta_roles_never_cross():
     assert ToolContext.current() is EMPTY
 
 
+def test_a_dict_meta_is_read_as_the_custom_entries():
+    """mcp 2 hands ``_meta`` over as a dict rather than a model with ``model_extra``."""
+    as_dict = SimpleNamespace(request_context=SimpleNamespace(meta={ROLE_META_KEY: "zed", SESSION_META_KEY: "s"}, request=None))
+    assert context_from_mcp(as_dict, "t", {}).caller == Caller("zed", "s")
+    assert context_from_mcp(_request_context({ROLE_META_KEY: "zed"}), "t", {}).caller == Caller("zed")
+    assert context_from_mcp(SimpleNamespace(request_context=SimpleNamespace(meta=42, request=None)), "t", {}).caller == Caller()
+
+
 @pytest.mark.asyncio
 async def test_header_fallback_and_default_blank_roles():
     env = _Env()