Live
Framework binding
For offline failure tests of newly bound LangGraph, LlamaIndex, Anthropic,
Microsoft Agent Framework, OpenAI Agents SDK and Strands
tools, see MCP tool fault injection.
It requires an explicit offline backend and does not intercept existing bindings
or bypass governance checks. Agent Framework simulation requires stable
agent-framework-core>=1.24.0 and mcp>=2.3.0; OpenAI Agents SDK simulation
requires stable openai-agents>=0.20.0 and mcp>=2.3.0; Strands simulation requires
stable strands-agents>=1.64.0 and mcp>=2.3.0. These do not change normal
production binding requirements.
Strands replay preserves its native generic error tool results, not typed PII
or access refusals; typed_refusals() cannot recover structured fields from
those results. Its native catalog errors still raise MCPError. Keep the native
client context inside the simulation scope. Failed, cancelled or expired Strands
sessions can emit an upstream unawaited-coroutine warning during stop() even
though their HTTP clients close. See the simulator page for ownership, restart
and bounded-test guidance.
Every binding below was run through the governed gateway with the framework’s current release: discovered from Exchange, then bound and called through an MCP instance behind JWT Validation and one behind Client ID Enforcement. The collision rename and the approval gate run in the SDK, and were run against local MCP servers.
Once discovery hands you a ToolSet, binding turns
governed MCP servers into a framework’s own tool objects — nothing wrapped,
nothing re-implemented.
MCP session management
MCP servers created by MCP Bridge are gateway endpoints speaking streamable HTTP, protected by gateway policies. The SDK’s session layer handles four things for you:
- Auth. Every binding sends your gateway consumer credential with each MCP request, and nothing else. See Auth.
- Connection lifecycle.
donkey.tools.discover()never opens a connection. The first binding call lists each server’s tools (tools/list) after the governance check, and the framework’s own MCP client connects when the agent uses the tools. - Multi-server aggregation.
ToolSetwraps NMcpServerHandles. When two servers expose a tool with the same name, the collision is resolved by prefixing the server’s short name — for examplehr__get_employee— and the mapping is available onToolSet.name_map, so you can see exactly why the model called that name. A name that would still be exposed twice, for example because two servers share a short name, raisesConfigErrorrather than dropping one of the tools. - Filtering. Enterprise MCP servers can expose dozens of tools. Handing 60 tool descriptors to a model degrades it and inflates token cost, so filter before you bind.
Install the MCP client with the framework’s extra, for example
pip install "donkey-kit[langgraph,mcp]" langchain-mcp-adapters. The [all]
extra includes mcp too. A binding whose packages are missing raises
ImportError with the command to run.
Auth
A governed MCP server is a gateway endpoint, so it takes the same consumer
credential as the LLM proxy. By default a binding sends the data-plane
credential you already configured, following llm_proxy_auth:
llm_proxy_auth | Headers sent |
|---|---|
client-id (the default) | client_id and client_secret, from DONKEY_LLM_PROXY_CLIENT_ID and DONKEY_LLM_PROXY_CLIENT_SECRET |
jwt, bearer | Authorization: Bearer <token>, from Donkey(llm_auth=...) |
It never sends the provider key, the wallet selector or the attribution headers: those belong to the LLM proxy. The consumer application needs a contract with each MCP instance, as it has with the LLM proxy.
When an MCP instance wants a different credential than the LLM proxy, pass one
to discover(auth=...). Anything with an async headers() and an async
invalidate() works, and the SDK ships two:
from donkey_kit.tools.auth import BearerAuth, ClientIdAuth
tools = await donkey.tools.discover(
tags=["hr"],
auth=ClientIdAuth("<client-id>", "<client-secret>"),
)
# or, for an instance behind JWT Validation:
tools = await donkey.tools.discover(tags=["hr"], auth=BearerAuth(my_provider))- A binding with no credential raises
ConfigErrorbefore any request. - The headers are read once per bind and handed to the framework’s MCP client as static headers, the one header argument every framework has. A bearer token is the one current at bind time, so bind again after it expires.
- A redirect never takes the credential to another origin. Where the framework
takes an HTTP client, a client factory or a transport, the binding passes
one that does not follow redirects and drops the credential, the user token
included, from any request to an origin other than the server’s. Agent
Framework removes its
static_headerson such a redirect itself. Bind to the URL with its trailing slash: an oldermcprelease, such as the 2.1 that Strands installs, then follows no redirect at all. - A
401or403while listing tools drops the cached credential and retries once, then raisesAuthError. A gateway step-up answer is the exception: it raisesGatewayApprovalPendingorGatewayApprovalDeniedat once and keeps the credential. To wait for the user instead, seewait_for_gateway_approval(). - Discovery reads the server URLs from the control plane at
base_url, so the credential followsbase_url’s rule. Ifbase_urlcomes from the working directory’s.donkey-kit.tomlor.donkey-kit.local.tomland isn’t a regional Anypoint host, then unlessDONKEY_TRUST_PROJECT_CONFIGis set, a discovered set sendsclient_idandclient_secretonly when they come from those files too, and never sends thellm_authtoken or adiscover(auth=...)credential. Instead, listing or binding raisesConfigErrorbefore anything is sent, naming each credential and where it came from. A set you build by hand has its URLs in code and isn’t checked. See Which credentials a URL receives.
A credential is often good for one instance only, such as a JWT whose audience
is that instance. Narrow the set to it with filter(servers=[...]) before you
bind, so the other servers are never listed and never receive the token:
tools = await donkey.tools.discover(auth=BearerAuth(hr_token))
hr = tools.filter(servers=["hr-mcp"]) # asset ID, or coordinates such as "<group-id>/hr-mcp/*"Acting for a user
Bind inside donkey.as_user() and the binding sends the user’s
token instead of your service’s, so the gateway’s on-behalf-of policy acts for
that user:
async with donkey.as_user(token=user_token):
tools = await (await donkey.tools.discover()).langgraph()
agent = create_react_agent(model, tools=tools)
await agent.ainvoke({"messages": [("user", question)]})- The token rides in the
user_token_header(Authorization: Bearer <token>by default). It replaces the credential’sAuthorization; the credential’s other headers, such asclient_idandclient_secret, still go. Inside the block a binding needs no credential of its own. - The token is read when you bind, like any credential, and the framework’s MCP client sends it on every call. A binding acts for the user it was bound for, so bind inside the block that runs the agent, once per user or request. A binding made outside any block acts as your service.
- A per-tool binding (
langgraph(),llamaindex(),anthropic()) refuses a call made under a different user than the one it was bound for. That covers another user’s token, a user’s binding called outside any block, and a service binding called inside one. The call raisesAuthErrorbefore anything is sent. An approved tool still runs as the user who asked for it, wherever it is resumed. - The token goes as you pass it. JWT Validation accepts it only if its audience names the MCP instance, so exchange the user’s login token at your identity provider for that audience first.
- A
401or403on the user’s token raisesAuthErrorwithout retrying: the SDK never falls back to your service’s credential. - The same
base_urlrule as for the credential applies to the user’s token. Ifbase_urlcomes from the working directory’s.donkey-kit.tomlor.donkey-kit.local.toml, a discovered set sends the user’s token only whenbase_urlis a regional Anypoint host orDONKEY_TRUST_PROJECT_CONFIGis set. Otherwise listing or binding inside the block raisesConfigErrorbefore anything is sent. The error names the token and any credential headers that would go with it. See Which credentials a URL receives.
A whole-server binding can’t be checked. adk(), strands(),
openai_agents(), agent_framework() and crewai() hand each server to the
framework, and the framework makes the tool calls itself, so the SDK never
sees them. Such a binding sends the identity it was bound with on every
call, whatever as_user() block the call runs in. Build an agent once at
startup and run each request inside as_user(), and its model calls go as
the user while its tool calls go as your service. Cache an agent built for
one user and reuse it for the next, and its tool calls go as the first user.
Bind a whole-server binding inside the as_user() block that uses it, and
don’t reuse it outside that block.
Gateway-visible catalogs
Bindings use the names, descriptions and schemas returned by the gateway’s
tools/list, not the upstream server’s original catalog. ToolSet.name_map
explains the SDK’s collision prefixes; it does not reverse a gateway rename.
With MCP Tool Mapping, use the mapped name in filters and approval rules.
For example, if the gateway exposes calculate as arithmetic:
tools = await (await donkey.tools.discover()).describe()
tools = tools.filter(allow=["arithmetic"]).require_approval(tools=["arithmetic"])A rule naming the hidden calculate raises ConfigError when the tools are
listed. The SDK does not translate that rule back to an upstream name.
With MCP Tools Progressive Disclosure, the default catalog contains
search_tools and invoke_tool. Bind those meta-tools as-is: the gateway owns
search and invocation. The SDK reports a catalog containing both names at info
level when describe() runs, before filtering; those names alone do not prove
which policy is installed. Additional listed tools remain ordinary tools.
A filter on a hidden upstream tool does not restrict what invoke_tool can
invoke. An approval rule on invoke_tool gates every call to that meta-tool,
not just a particular value of its name argument. Use gateway access
policies for enforcement. Client-side approval remains advisory, and
whole-server bindings still cannot apply require_approval() rules.
The mapped catalog and call, and the default progressive-disclosure catalog, were observed through the gateway. Filter and approval naming are covered by offline replay of those catalogs, not a live policy-and-approval round trip. No client-side search, TOON decoding or policy enforcement is added.
Filtering
filter() takes an allow-list, a deny-list and a predicate, and deny wins.
Allow and deny entries are exact names or glob patterns, matched against the
bare tool name and the server-qualified one (hr__get_employee, hr__*):
tools = await donkey.tools.discover(tags=["hr"])
filtered = tools.filter(allow=["get_employee", "search_employees"])
# or:
filtered = tools.filter(deny=["delete_*"])
# or a predicate over the tool descriptor:
filtered = tools.filter(predicate=lambda t: t.description and len(t.description) > 40)Each call returns a new ToolSet, and chained calls narrow through every
filter. A later call can never bring back a tool an earlier one removed:
final = (tools
.filter(allow=["get_*", "search_*"])
.filter(deny=["get_ssn"])
.filter(predicate=lambda t: "internal" not in t.tags))Filtering only narrows. It removes tools from what the model sees. It never adds a tool the servers did not expose, and it never widens what the gateway allows: gateway policies still apply to every call.
An allow or deny entry that matches no tool on any server raises ConfigError
once the tools are listed, at describe() or at bind time. A typo then can’t
empty the set or leave a tool you meant to deny exposed.
filter(servers=[...]) narrows the servers instead, by asset ID or
coordinates, exact or glob. It applies before any tool is listed, so a server
it drops is never connected to. An entry that matches no server in the set
raises ConfigError straight away.
What the tool list costs
Every model call carries the descriptors of the tools it can call.
descriptor_tokens() estimates that cost for the set after filtering. A
discovered server’s tools are unknown until they are listed, so call
describe() first (every binding calls it for you):
tools, final = await tools.describe(), await final.describe()
print(f"{tools.descriptor_tokens()} -> {final.descriptor_tokens()} descriptor tokens per call")
# 9120 -> 812 descriptor tokens per callIt counts each descriptor’s name, description and input schema as an OpenAI-style function tool, at about four characters per token. Tokenizers differ by model, so use it to compare tool sets, not as a bill.
Every binding logs the number of tools it binds and this estimate at debug
level, and logs a warning when the set has more than tool_warn_count tools
(default 20) or costs more than tool_warn_tokens (default 10000):
WARNING donkey_kit.tools.session: langgraph() binds 34 tool descriptors, about 9120 descriptor tokens per model call (more than tool_warn_count=20). Large tool sets degrade tool selection and cost tokens on every call: narrow the set with filter(), or raise the threshold (0 turns it off).The defaults follow the model vendors’ published guidance on tool count and descriptor size; see Tool-set size warnings for the sources and how to change or turn off each threshold.
The SDK also logs how many tool descriptors a ToolSet exposes out of the
total at debug level, so you can see the cost of skipping filter() before a
model does. See Debug logging to turn it on.
Only governed servers are bound
Binding refuses a set that holds any MCP server the gateway does not govern,
with UngovernedMcpServer. That covers a server
registered in Exchange but not fronted by the gateway, and one whose governance
was never evaluated, and one that does not resolve to exactly one deployed MCP
instance. The refusal happens before any connection opens, so:
- No credentials leak. The SDK attaches your gateway credentials to every governed request. It never sends them to a server the gateway does not front.
- No ungoverned tool calls. Gateway policies, access profiles and the kill switch apply to every tool the agent can call.
The error names each refused server (.servers) and each governance check it
failed (.reasons, from explain()):
from donkey_kit import UngovernedMcpServer
ts = await donkey.tools.discover(tags=["crm"], governed=None) # unfiltered: lists everything
try:
tools = await ts.langgraph()
except UngovernedMcpServer as e:
print(e.servers) # ('com.acme/fastmcp-crm/1.0.0',)
print(e.reasons) # ('com.acme/fastmcp-crm/1.0.0: deployed: no gateway in Sandbox',)To fix it, front the server with the gateway, or leave it out: the default
discover() (governed=True) does, so drop governed=None, or drop the
server with filter(servers=[...]). A tool
filter (allow, deny, predicate) does not get you past the check: the
server is still in the set. There is no opt-out: to call an ungoverned server, use
the framework’s own MCP client, without the SDK and without your gateway
credentials.
To put a human decision in front of a sensitive tool, declare it on the set
with require_approval(tools=[...], risk=...) before you bind (see
“Discovered tools” in Human-in-the-loop).
Per-framework binding
ToolSet exposes one method per framework, each returning the framework’s
native MCP objects. They are async, because each lists the tools first:
ts = await donkey.tools.discover(tags=["hr"])
await ts.langgraph() # -> list[BaseTool]
await ts.llamaindex() # -> list[FunctionTool]
async with ts.anthropic() as tools: # -> list[BetaAsyncFunctionTool]
...
await ts.adk() # -> list[McpToolset], one per server
await ts.strands() # -> list[MCPClient], one per server
await ts.openai_agents() # -> list[MCPServerStreamableHttp], one per server
await ts.agent_framework() # -> list[MCPStreamableHTTPTool], one per server
async with ts.crewai() as tools: # -> list[BaseTool]
...| Framework | Binding | Install |
|---|---|---|
| LangGraph | langchain_mcp_adapters.client.MultiServerMCPClient, transport "streamable_http", with the SDK’s httpx_client_factory. Returns a flat list of tools for create_react_agent(tools=...) or a ToolNode; each call opens its own session. | donkey-kit[langgraph,mcp], langchain-mcp-adapters (needs mcp<2) |
| LlamaIndex | llama_index.tools.mcp.BasicMCPClient(url, http_client=...) + McpToolSpec(...).to_tool_list_async(). A flat list of tools; each call opens its own session. | donkey-kit[llamaindex,mcp], llama-index-tools-mcp |
| Anthropic SDK | anthropic.lib.tools.mcp.async_mcp_tool(tool, session) over an MCP ClientSession per server, for client.beta.messages.tool_runner(tools=...). An async context manager: the sessions close on exit. The Messages API mcp_servers connector is not used: Anthropic’s servers dial that URL, and it has no field for the gateway’s credential headers. | donkey-kit[anthropic,mcp] |
| Google ADK | google.adk.tools.mcp_tool.McpToolset(connection_params=StreamableHTTPConnectionParams(url=..., headers=..., httpx_client_factory=...), tool_filter=[...]), passed straight into LlmAgent(tools=[...]). Close it with await toolset.close(). | donkey-kit[adk,mcp] |
| Strands | strands.tools.mcp.MCPClient(transport_callable=..., tool_filters=...), used as a context manager; list_tools_sync() yields MCPAgentTool objects for Agent(tools=[...]). | donkey-kit[strands,mcp] |
| OpenAI Agents SDK | agents.mcp.MCPServerStreamableHttp(params={"url": ..., "headers": ..., "httpx_client_factory": ...}, tool_filter=...), entered with async with and passed into Agent(mcp_servers=[...]). | donkey-kit[openai-agents,mcp] |
| MS Agent Framework | agent_framework.MCPStreamableHTTPTool(name, url, static_headers=..., allowed_tools=...), entered with async with. It has no headers= argument; the gateway credentials go in static_headers. | donkey-kit[agent_framework,mcp] |
| CrewAI | crewai_tools.MCPServerAdapter({"url": ..., "transport": "streamable-http", "headers": ..., "httpx_client_factory": ...}, *tool_names), one per server, for Agent(tools=...). An async context manager: the adapters hold their connections open and stop on exit. filter() becomes the tool_names allow-list. | donkey-kit[crewai,mcp], crewai-tools[mcp] (needs mcp<2) |
Each class in this table, and the argument that carries the gateway’s
credential headers, was checked by binding the framework’s current release to
a local MCP server. The SDK’s bindings were run against two local servers for
the filter, the collision rename and the approval gate described here, and
then through the governed gateway: each one bound an MCP instance discovered
from Exchange, behind JWT Validation and behind Client ID Enforcement, and
called a tool on it. Another instance’s token, or a wrong client secret, raised
AuthError.
Whole-server bindings
ADK, Strands, the OpenAI Agents SDK, Agent Framework and CrewAI bind each MCP
server as one object. filter() becomes that object’s allow-list of tool names, but the
object cannot rename one tool or gate one call, so:
- a set whose tool names collide across servers raises
ConfigError. Keep one of each clashing tool withfilter(deny=[...]), or bind with LangGraph, LlamaIndex or the Anthropic SDK, which rename it; - a set with a
require_approval()rule raisesConfigError. Gate discovered tools through LangGraph, LlamaIndex or the Anthropic SDK, or use the framework’s own approval hook (see Human-in-the-loop); - a tool call made under a different
as_user()user from the bind’s is not refused: it goes out with the identity of the bind. See Acting for a user.
Results and errors
The frameworks return a tool call’s result in different shapes: a plain string, MCP content blocks, structured JSON, or a wrapper object. Each binding leaves the framework’s own result type unchanged, so don’t assume a bare string.
A binding failure surfaces as a typed exception from the
error taxonomy: AuthError when the gateway refuses the
credential, ToolInvocationError when a server cannot list its tools, and
UngovernedMcpServer for an ungoverned server (above). A binding that leaves
no tool to bind, because filter() removed them all or the set is empty, logs
why at info level and returns an empty list.
During MCP listing and binding, HTTP error bodies are buffered only when they
are complete, identity-encoded and at most 64 KiB. The five-second total
deadline covers both reading and best-effort cleanup; a stalled close does not
add another timeout. Cancellation propagates without waiting for cleanup.
Oversized, compressed, interrupted or slow bodies are not classified from
partial bytes. Status and headers remain available: an authentication status
can still raise AuthError, while an unclassifiable listing failure raises
ToolInvocationError. A partial body never becomes an approval response.
For locked per-tool metadata guarantees and whole-server limitations, see
Pinning & lockfile.
Tools outside your access profile
The gateway’s MCP access policies (MCP Global Access and Attribute-Based Access Control) decide which tools each consumer may call. They act in two places:
- Discovery is scoped by the server. A tool you may not call is left out of
that server’s
tools/listfor you, so the SDK never sees it and never binds it.ToolSet.excludedlists only the tools your ownfilter()calls removed (reason="filter"), not these. - A call to a denied tool is refused. A stale tool list, or a policy changed
after you bound, can still lead to one. The gateway answers with HTTP
200and the JSON-RPC error-32008"Unable to access". It names the tool but not the profile or rule that refused it.
The LangGraph, LlamaIndex and Anthropic bindings raise ToolNotInProfile (a
PolicyViolation) from that call, with
.tool_name and the server’s coordinates in .server. It is a configuration
problem, so it is never retried. The whole-server bindings leave the call to
the framework. The OpenAI Agents SDK and CrewAI raise the mcp package’s
McpError, and Agent Framework wraps it in its ToolExecutionException.
typed_refusals(), also
applied by donkey.run(), recovers the typed error from these raised errors.
Unlike a per-tool binding, the recovered error has no server coordinates.
The existing tool_access_denial() helper remains available for manual conversion:
from donkey_kit import ToolNotInProfile
from donkey_kit.experimental import tool_access_denial
try:
result = await server.call_tool("lookup_proxy", {"name": "orders"})
except Exception as exc:
if (denied := tool_access_denial(exc)) is not None:
raise denied from exc
raiseADK and Strands hand the agent an error result whose text is
... Unable to access, without the JSON-RPC code. The SDK doesn’t classify
it, because the text alone could be any tool’s failure. In the same way, a
tool that ran and failed returns a result with isError: true, never
ToolNotInProfile.
MCP policy refusals
See MCP gateway policies for the policy inventory, gateway-visible catalog changes and the limits of each captured behavior.
Captured MCP PII Detector refusals on tool requests and responses raise
PIIDetected through LangGraph, LlamaIndex and Anthropic bindings. With
OpenAI Agents and Agent Framework, wrap the framework call in
typed_refusals() (or donkey.run()) to recover the same type. Its .phase,
.entities and .findings contain safe metadata, not blocked values.
The original framework exception is available as .framework_error; it may
contain gateway diagnostics, so do not log it as safe metadata.
Already-typed exceptions retain their identity, existing cause and framework
metadata. Malformed or unmarked MCP HTTP 403 responses remain HTTP errors,
not inferred policy refusals.
ADK and Strands instead return error text and lose the structured policy fields. The SDK never infers a policy from that text. With the locked CrewAI MCP 1.x stack, replaying the captured HTTP 403 PII refusal leaves the tool call unresolved; this path is not supported as a typed refusal. All these binding results were checked locally against captured responses, not through live framework calls to the gateway.
Schema-validation and tool-poisoning errors without explicit policy markers
remain ambiguous, not typed policy refusals. Successful results and
isError: true tool results keep their framework-native behavior.
Related
- Discovery, search & filter — produce the
ToolSet. - A2A agent tools — bind a remote agent the same way.
- Frameworks — governed model access per framework.