Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/integrations/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Every other attribute is the wrapped session's. Only calls made through the wrap
| before the call is sent | `decide` | a fresh `tool_call_id`, the tool as `mcp:<server>/<tool>` (`mcp:<server>/prompt:<name>` for `get_prompt`), `tool_class_hint: mcp`, the arguments as given (`parsed`) |
| right before it is sent | `approval_consume` | the same call and arguments, and the approval id when the call waited for one |
| after the server answers | `complete` | `status` `ok`, or `error` for a result with `isError: true`; a `sha256:` commitment to the result (not the result), or the exception type and message |
| after `read_resource` answers | `observe` | `source` `mcp:<server>/resource`, `trust: untrusted` and the result as `value` (recorded as its commitment and indexed for provenance; a result over half the signer's 1 MiB frame as its `sha256:` digest; withheld if the signer cannot record it, unless the run fails open for `mcp` and the signer is unreachable, when it warns and returns the result; a refusal is withheld either way) |

`list_tools`, `list_resources` and `list_prompts` are recorded as untrusted observed input (`observe`, source `mcp:<server>/tools`, `/resources` or `/prompts`): the model reads the descriptions the server wrote, and the page the caller asked for is what is recorded (a page over half the signer's 1 MiB frame as its `sha256:` digest, as the [MCP gateway](../mcp-gateway.md) records one). The list mcp's `call_tool` makes itself, to check a result against the tool's output schema, never reaches the model and isn't recorded. A page the signer cannot record is withheld, unless the run fails open for `mcp`, when an unreachable signer returns it with a warning; a refusal is withheld either way. A tool call or prompt that returns an `InputRequiredResult` (MCP 2.3) records each round's input requests as untrusted observed input (`observe`, source `mcp:<server>/input_required`). When the server provides a `request_state` and the decision is `allow`, it is decided and completed once, under its initial decision, when the terminal result arrives. A round continues the call its own asyncio task left waiting, as `mcp.Client.call_tool` drives the rounds, so concurrent calls never share a decision even when the server returns the same `request_state` to both; a waiting call whose task calls a tool or gets a prompt on the session first is never completed ([not covered](#not-covered)). Rounds from a server that returns no `request_state`, or under a decision that isn't `allow` (a flag, or an ask, whose approval the signer consumes only once), are decided and completed as separate calls per round.

Expand Down
2 changes: 2 additions & 0 deletions tests/test_agent_framework.py
Original file line number Diff line number Diff line change
Expand Up @@ -443,6 +443,7 @@ def list_files(path: str) -> str:
return "README.md"
self.addCleanup(setattr, ClientSession, "call_tool", ClientSession.call_tool)
self.addCleanup(setattr, ClientSession, "get_prompt", ClientSession.get_prompt)
self.addCleanup(setattr, ClientSession, "read_resource", ClientSession.read_resource)
self.addCleanup(setattr, ClientSession, "initialize", ClientSession.initialize)
for name in ("list_tools", "list_resources", "list_prompts"):
if hasattr(ClientSession, name):
Expand All @@ -456,6 +457,7 @@ async def main(r):
return (await a.run("list them")).text
with mock.patch.object(ClientSession, "call_tool", ClientSession.call_tool), \
mock.patch.object(ClientSession, "get_prompt", ClientSession.get_prompt), \
mock.patch.object(ClientSession, "read_resource", ClientSession.read_resource), \
mock.patch("tracekit.integrations.mcp.TracekitSession") as gate:
autowire._mcp(mock.Mock()) # what instrument() wires: every ClientSession decides its calls
for r, runs in ((run(), True), (run("deny", ["D1"]), False)):
Expand Down
78 changes: 73 additions & 5 deletions tests/test_contract_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -146,22 +146,29 @@ async def get_prompt(self, name, arguments=None):
raise MCPError(-32603, "boom")
return GetPromptResult(messages=[PromptMessage(role="user", content=TextContent(type="text", text="hi"))])

async def read_resource(self, uri, *a, **kw):
from mcp.types import ReadResourceResult, TextResourceContents
self.calls += 1
return ReadResourceResult(contents=[TextResourceContents(uri=uri, text=f"body of {uri}")])


class _StubSession(_Mcp1Session):
server_info = type("Info", (), {"name": "stub"})()


class _Signer:
"""A signer that fails the way it is told: `decide` and `complete` raise `errors[method]` when set."""
"""A signer that fails the way it is told: `decide`, `complete` and `observe` raise `errors[method]` when set."""

def __init__(self, decision="allow", **errors):
self.decision, self.errors, self.tools, self.completed, self.requests = decision, errors, [], [], []
self.decision, self.errors, self.tools, self.completed = decision, errors, [], []
self.observed, self.requests = [], []

def __getattr__(self, method):
def call(req):
self.requests.append((method, req))
self.tools += [req["tool"]] if method == "decide" else []
self.completed += [req] if method == "complete" else []
self.observed += [req] if method == "observe" else []
if method in self.errors:
raise self.errors[method]
return {"decide": {"decision": self.decision, "decision_id": "dec-1", "rule_ids": ["r1"]},
Expand Down Expand Up @@ -254,11 +261,70 @@ def test_get_prompt_is_decided_and_completed_as_a_prompt_call(self):
run = mock.Mock(client=signer, registered=self.RUN)
with mock.patch("mcp.ClientSession", _StubSession), \
mock.patch.object(_StubSession, "call_tool", _StubSession.call_tool), \
mock.patch.object(_StubSession, "get_prompt", _StubSession.get_prompt):
mock.patch.object(_StubSession, "get_prompt", _StubSession.get_prompt), \
mock.patch.object(_StubSession, "read_resource", _StubSession.read_resource):
autowire._mcp(run)
out = asyncio.run(_StubSession().get_prompt("triage", {"issue": "1"}))
self.assertEqual((out.messages[0].content.text, signer.tools), ("hi", ["mcp:stub/prompt:triage"]))

def test_read_resource_is_recorded_as_an_untrusted_observed_input(self):
session, signer = _StubSession(), _Signer()
out = asyncio.run(TracekitSession(session, signer, self.RUN).read_resource("note://inbox"))
self.assertEqual((out.contents[0].text, session.calls), ("body of note://inbox", 1))
self.assertEqual([(r["source"], r["trust"], r["value"]["contents"][0]["text"]) for r in signer.observed],
[("mcp:stub/resource", "untrusted", "body of note://inbox")])

from tracekit import autowire
signer = _Signer()
run = mock.Mock(client=signer, registered=self.RUN)
with mock.patch("mcp.ClientSession", _StubSession), \
mock.patch.object(_StubSession, "call_tool", _StubSession.call_tool), \
mock.patch.object(_StubSession, "get_prompt", _StubSession.get_prompt), \
mock.patch.object(_StubSession, "read_resource", _StubSession.read_resource):
autowire._mcp(run)
out = asyncio.run(_StubSession().read_resource("note://inbox"))
self.assertEqual((out.contents[0].text, [(r["source"], r["trust"]) for r in signer.observed]),
("body of note://inbox", [("mcp:stub/resource", "untrusted")]))

def test_an_unrecorded_resource_is_withheld_when_the_run_fails_closed(self):
"""The default fail mode is closed, and a signer refusal is withheld even when the run fails open."""
from tracekit.sdk.client import SignerUnavailable
from tracekit.signer.rpc_schema import RPCError
session = _StubSession()
with self.assertRaises(SignerUnavailable):
asyncio.run(TracekitSession(session, _Signer(observe=SignerUnavailable("down")),
self.RUN).read_resource("note://inbox"))
self.assertEqual(session.calls, 1) # fetched from the server, not returned
with self.assertRaises(RPCError):
asyncio.run(TracekitSession(_StubSession(), _Signer(observe=RPCError("unavailable", "storage down")),
self.RUN).read_resource("note://inbox"))
with self.assertRaises(RPCError):
asyncio.run(TracekitSession(_StubSession(), _Signer(observe=RPCError("unavailable", "storage down")),
{**self.RUN, "fail_modes": {"mcp": "open"}}).read_resource("note://inbox"))

def test_an_unrecorded_resource_is_returned_when_the_run_fails_open(self):
from tracekit.sdk.client import SignerUnavailable
session = _StubSession()
with self.assertWarns(UserWarning) as cm:
gate = TracekitSession(session, _Signer(observe=SignerUnavailable("down")),
{**self.RUN, "fail_modes": {"mcp": "open"}})
out = asyncio.run(gate.read_resource("note://inbox"))
self.assertEqual((out.contents[0].text, session.calls), ("body of note://inbox", 1))
self.assertIn("not recorded", str(cm.warning))

def test_a_resource_over_half_a_frame_is_recorded_as_its_digest(self):
from mcp.types import ReadResourceResult, TextResourceContents
from tracekit.format.canon import event_hash

class Big(_StubSession):
async def read_resource(self, uri, *a, **kw):
return ReadResourceResult(contents=[TextResourceContents(uri=uri, text="x" * (1 << 20))])
signer = _Signer()
out = asyncio.run(TracekitSession(Big(), signer, self.RUN).read_resource("note://inbox"))
self.assertEqual(len(out.contents[0].text), 1 << 20)
self.assertEqual([r["value"] for r in signer.observed],
[event_hash(out.model_dump(mode="json", by_alias=True, exclude_none=True))])


class _ListingSession(_StubSession):
"""List methods return one page, the one `params.cursor` names (the first when the caller asks for none)."""
Expand Down Expand Up @@ -366,6 +432,7 @@ def test_instrument_observes_a_sessions_lists(self):
with mock.patch("mcp.ClientSession", _ListingSession), \
mock.patch.object(_ListingSession, "call_tool", _ListingSession.call_tool), \
mock.patch.object(_ListingSession, "get_prompt", _ListingSession.get_prompt), \
mock.patch.object(_ListingSession, "read_resource", _ListingSession.read_resource), \
mock.patch.object(_ListingSession, "list_tools", _ListingSession.list_tools), \
mock.patch.object(_ListingSession, "list_resources", _ListingSession.list_resources), \
mock.patch.object(_ListingSession, "list_prompts", _ListingSession.list_prompts):
Expand All @@ -385,7 +452,7 @@ def setUp(self):
from mcp.client.session import ClientSession
self.orig_methods = {
m: getattr(ClientSession, m)
for m in ("call_tool", "get_prompt", "list_tools", "list_resources", "list_prompts")
for m in ("call_tool", "get_prompt", "read_resource", "list_tools", "list_resources", "list_prompts")
if hasattr(ClientSession, m)
}
self.addCleanup(self._restore)
Expand Down Expand Up @@ -914,7 +981,8 @@ def setUp(self):
from tracekit import autowire
from tracekit.policy2.engine import Engine
from tracekit.signer.service import SignerService
for name in ("call_tool", "get_prompt", "list_tools", "list_resources", "list_prompts"): # autowire patches them
for name in ("call_tool", "get_prompt", "read_resource", "list_tools", "list_resources",
"list_prompts"): # autowire patches them
patcher = mock.patch.object(ClientSession, name, getattr(ClientSession, name))
patcher.start()
self.addCleanup(patcher.stop)
Expand Down
2 changes: 2 additions & 0 deletions tests/test_instrument.py
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,7 @@ async def call_tool(gate, *a, **kw):
run = mock.Mock(registered={"run_id": "r", "run_token": "t"})
with mock.patch.object(ClientSession, "call_tool", ClientSession.call_tool), \
mock.patch.object(ClientSession, "get_prompt", ClientSession.get_prompt), \
mock.patch.object(ClientSession, "read_resource", ClientSession.read_resource), \
mock.patch.object(ClientSession, "list_tools", ClientSession.list_tools), \
mock.patch.object(ClientSession, "list_resources", ClientSession.list_resources), \
mock.patch.object(ClientSession, "list_prompts", ClientSession.list_prompts), \
Expand All @@ -272,6 +273,7 @@ async def call_tool(gate, *a, **kw):
run = mock.Mock(registered={"run_id": "r", "run_token": "t"})
with mock.patch.object(ClientSession, "call_tool", ClientSession.call_tool), \
mock.patch.object(ClientSession, "get_prompt", ClientSession.get_prompt), \
mock.patch.object(ClientSession, "read_resource", ClientSession.read_resource), \
mock.patch.object(ClientSession, "list_tools", ClientSession.list_tools), \
mock.patch.object(ClientSession, "list_resources", ClientSession.list_resources), \
mock.patch.object(ClientSession, "list_prompts", ClientSession.list_prompts), \
Expand Down
2 changes: 2 additions & 0 deletions tests/test_pydantic_ai.py
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,8 @@ def test_a_call_the_capability_decided_is_not_decided_again_by_the_wired_mcp_ses
from mcp import ClientSession
original = mock.AsyncMock(return_value="result")
self.addCleanup(setattr, ClientSession, "call_tool", ClientSession.call_tool)
self.addCleanup(setattr, ClientSession, "get_prompt", ClientSession.get_prompt)
self.addCleanup(setattr, ClientSession, "read_resource", ClientSession.read_resource)
self.addCleanup(setattr, ClientSession, "initialize", ClientSession.initialize)
for name in ("list_tools", "list_resources", "list_prompts"):
if hasattr(ClientSession, name):
Expand Down
6 changes: 3 additions & 3 deletions tracekit/autowire.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
`handle_tool_errors`, and through `.with_fallbacks()`;
* Claude Agent SDK: every ClaudeAgentOptions built from now on gets the PreToolUse and PostToolUse hooks
(tracekit_hooks);
* MCP client: every ClientSession.call_tool goes through TracekitSession, and its list_tools, list_resources and
list_prompts are recorded as untrusted input;
* MCP client: every ClientSession.call_tool goes through TracekitSession, and its read_resource, list_tools,
list_resources and list_prompts are recorded as untrusted input;
* Browser Use: the actions of every Tools built from now on (an Agent builds one) are gated (trace_tools);
* CrewAI: global tool hooks decide every tool call and block by return value (tracekit.integrations.crewai);
* Pydantic AI: every Agent built from now on gets the Tracekit capability (tracekit.integrations.pydantic_ai), unless
Expand Down Expand Up @@ -266,7 +266,7 @@ def _mcp(run):

from .integrations.mcp import TracekitSession
methods = {}
for name in ("call_tool", "get_prompt", "list_tools", "list_resources", "list_prompts"):
for name in ("call_tool", "get_prompt", "read_resource", "list_tools", "list_resources", "list_prompts"):
orig = getattr(ClientSession, name, None)
if orig is not None: # get_prompt is absent on mcp 1.x
methods[name] = orig
Expand Down
35 changes: 20 additions & 15 deletions tracekit/integrations/mcp.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
"""MCP client (python `mcp` package): every `call_tool` and `get_prompt` on a ClientSession is decided by the signer
before it is sent to the server and recorded after.
before it is sent to the server and recorded after, and `read_resource` records what it returns as an observed input.

from tracekit.integrations.mcp import TracekitSession
run = signer.register_run({"request_id": "r1", "agent": {"name": "my-agent"}})
Expand All @@ -19,11 +19,12 @@
signer's decided_not_completed gap at run close. Rounds without `request_state`, or whose decision isn't `allow` (a
flag or an ask), are decided as calls of their own. A result with `isError: true` completes as an error; an exception from the session
propagates unchanged and completes as an error.
`list_tools`, `list_resources` and `list_prompts` are recorded as untrusted observed input (`mcp:<server>/tools`,
`/resources`, `/prompts`; a page over half a signer frame as its digest) and returned once recorded. A list the signer
cannot reach is withheld unless the run fails open for this class, when it is returned with a warning; a refusal is
withheld either way. The list mcp itself asks for inside `call_tool` (to check a result against the tool's output
schema) never reaches the model and isn't recorded. Only those calls made through the wrapped session are seen.
`read_resource`, `list_tools`, `list_resources` and `list_prompts` are recorded as untrusted observed input
(`mcp:<server>/resource`, `/tools`, `/resources`, `/prompts`; a result over half a signer frame as its digest) and
returned once recorded. A resource or list the signer cannot reach is withheld unless the run fails open for this
class, when it is returned with a warning; a refusal is withheld either way. The list mcp itself asks for inside
`call_tool` (to check a result against the tool's output schema) never reaches the model and isn't recorded. Only
those calls made through the wrapped session are seen.
"""
import asyncio
import functools
Expand Down Expand Up @@ -67,34 +68,38 @@ async def call_tool(self, name, arguments=None, *a, **kw):
async def get_prompt(self, name, arguments=None, *a, **kw):
return await self._call("get_prompt", "prompt:", name, arguments, *a, **kw)

async def read_resource(self, uri, *a, **kw):
return await self._observed("read_resource", "resource", uri, *a, **kw)

async def list_tools(self, *a, **kw):
return await self._list("tools", *a, **kw)
return await self._observed("list_tools", "tools", *a, **kw)

async def list_resources(self, *a, **kw):
return await self._list("resources", *a, **kw)
return await self._observed("list_resources", "resources", *a, **kw)

async def list_prompts(self, *a, **kw):
return await self._list("prompts", *a, **kw)
return await self._observed("list_prompts", "prompts", *a, **kw)

def _server_name(self):
"""(the name the session gave, or None; the `mcp:<name>` component, `unknown` when it gave none)."""
raw = self._server or getattr(getattr(self._session, "server_info", None), "name", None)
return raw, _UNSAFE.sub("_", raw or "") or "unknown"

async def _list(self, kind, *a, **kw):
"""The page `list_<kind>` returned, once recorded as untrusted input the model reads. An unreachable signer
returns it only when the run fails open for this class; a refusal is withheld either way."""
out = await getattr(self._session, "list_" + kind)(*a, **kw)
async def _observed(self, method, kind, *a, **kw):
"""What the session's `method` returned (a resource, a list's page), once recorded as untrusted input the model
reads (`mcp:<server>/<kind>`). An unreachable signer returns it only when the run fails open for this class; a
refusal is withheld either way."""
out = await getattr(self._session, method)(*a, **kw)
raw, server = self._server_name()
if not raw:
warnings.warn(_UNNAMED, stacklevel=4) # list_* -> _list -> warn: the caller's line, as _call's warning
warnings.warn(_UNNAMED, stacklevel=4) # list_* -> _observed -> warn: the caller's line, as _call's warning
try:
await self._rpc("observe", source=f"mcp:{server}/{kind}", trust="untrusted",
value=result_field(True, out.model_dump(mode="json", by_alias=True, exclude_none=True)))
except SignerUnavailable as e: # unreachable: the run's fail mode for this class, as _gate
if not fail_open(self.fail_modes, self.CLASS):
raise
warnings.warn(f"tracekit: MCP {kind} list not recorded: {e}", stacklevel=2)
warnings.warn(f"tracekit: MCP {kind} not recorded: {e}", stacklevel=2)
return out

async def _send(self, method, *a, **kw):
Expand Down
Loading