Live
Discovery, search & filter
donkey.tools.discover() composes three live registry reads:
donkey.registry.search(),
donkey.registry.explain() and
donkey.registry.resolve_mcp(). What it returns
has been bound and called through the governed gateway with every supported
framework (see Framework binding).
donkey.tools.discover(...) is the one entry point for finding governed tools
to bind. It narrows the catalog by governance and tags, so an agent
binds only the tools it needs rather than the entire catalog. It returns a
ToolSet whose per-framework methods hand back native
tool objects. Name search and asset type are filters on the lower-level
donkey.registry.search().
The two most common calls
# 1. Every governed MCP server (governed=True is the default):
tools = await donkey.tools.discover()
# 2. Governed MCP servers that carry a tag:
tools = await donkey.tools.discover(tags=["approved"])Filter reference
Every argument is keyword-only and optional, and filters combine with AND
semantics:
tools = await donkey.tools.discover(
tags=["approved"], # all tags must be present
governed=True, # the default: default criteria; or an explicit GovernanceCriteria
auth=None, # None = the data-plane consumer credential
)| Argument | Type | Meaning |
|---|---|---|
domain | str | None | Catalog domain. Raises NotImplementedError for now: Exchange has no domain filter. |
tags | list[str] | None | All listed tags must be present. |
governed | bool | GovernanceCriteria | None | True (the default) applies the default criteria; pass a GovernanceCriteria (e.g. STRICT) for explicit rules; None = unfiltered. |
locked | bool | True reads donkey.lock and checks the set against it: drift raises ToolLockDrift, and unpinned tools are dropped (see Pinning & lockfile). Provisional. Default False. |
lock_path | str | PathLike | The lockfile locked=True reads. Default "donkey.lock". |
auth | McpAuth | None | The gateway credential bindings send. None uses the data-plane consumer credential; see Auth. |
It reads at most 200 MCP assets, and logs a warning when it reaches that limit;
narrow it with tags=. A server that does not resolve to exactly one deployed
MCP instance in the environment is listed with a failed resolve_mcp check, so
governed=True leaves it out and binding refuses it.
Catalog-changing policies
Discovery finds servers, not their current tool names. It opens no MCP
connection, so MCP Tool Mapping and Tools Progressive Disclosure become visible
only when you call describe() or bind. Use the gateway-visible names in
filters and approval rules; see
Gateway-visible catalogs.
For access-scoped lists, refusal handling and result transformations, see
MCP gateway policies.
When listing tools, the SDK retains HTTP error bodies for classification only
within a 64 KiB limit and a five-second total deadline shared by the read and
best-effort cleanup, with no compressed or partial envelope classification.
Cancellation is not delayed by cleanup. Authentication failures remain AuthError; other
listing failures surface as ToolInvocationError. See
Results and errors.
Registry search
donkey.registry.search() is Live. discover(...)
is the high-level facade over the registry. When you need name search, asset
types or a result limit, call donkey.registry.search() directly. It returns
AssetRef handles rather than a bindable ToolSet:
refs = await donkey.registry.search(
query="*accounts*", # a glob over asset ID, name and description; None = no text filter
asset_types=["mcp"], # "mcp", "agent", "api" or "llm"
tags=["approved"], # all tags must be present
limit=50, # max results (default 50)
)
for ref in refs:
print(ref.coordinates, ref.name, ref.type, ref.tags)It searches the business group in ANYPOINT_ORG_ID and returns each asset’s
latest version:
- A
querywithout*,?or[is matched by Exchange: whole words and word prefixes of the asset ID, name or description, ignoring case."sku"and"look"findSKU Lookup MCP Server;"ku-loo"does not. - A
querywith*,?or[is a glob, matched by the SDK against the asset ID, name and description, ignoring case. Exchange does not match inside words, so a glob query reads the group’s assets that pass the other filters, 250 at a time, until it haslimitmatches. asset_typesandtagsare applied by Exchange."api"covers Exchange’s REST, HTTP and SOAP API types."llm"is an LLM proxy or a custom LLM provider; read what one declares withdonkey.registry.llm_metadata(). A tag is an Exchange tag.domain,environment,governedand the"a2a-agent"type raiseNotImplementedErrorfor now. Exchange has no domain filter, andenvironmentandgovernedneed the governed-state join below.
Resolving an MCP server
donkey.registry.resolve_mcp() is Live. It turns an
MCP server asset into the gateway URL an agent connects to:
server = await donkey.registry.resolve_mcp("<group-id>/sku-lookup-mcp/1.1.0")
print(server.endpoint_url) # https://<gateway-host>/<instance-path>/It looks for the asset version’s API Manager instance in the environment set by
ANYPOINT_ENV (default Sandbox) that is deployed to a gateway, and joins the
gateway’s public URL with the instance’s path. The URL ends in /: the gateway
routes the path only with the trailing slash.
- It raises
RegistryErrorwhen the environment does not exist, when the version has no deployed MCP instance there, or when it has more than one. - The gateway URL receives the gateway credential, so it follows the same rule
as the URLs you configure (see
Endpoints must use
https://): it must behttps://. Plainhttp://is accepted for a loopback host, and for any other host only withDONKEY_ALLOW_HTTP=1in the environment, with aConfigWarning. A gateway public URL that is not, or that carries a user name or password, raisesRegistryError.discover()then lists the server with a failedresolve_mcpcheck, and binding refuses it. - It does not open a connection or send the gateway’s client credentials. Calls through the URL need them, because the gateway’s Client ID Enforcement policy refuses a call without them.
- The returned handle’s
governanceisNone: whether the instance is governed comes fromexplain(). - Results are cached like the other registry lookups; see Registry caching.
Resolving an A2A agent
donkey.registry.resolve_agent() is Live. It does
for an A2A agent asset what resolve_mcp() does for an MCP server, with the
same reads, and finds the version’s deployed A2A instance:
agent = await donkey.registry.resolve_agent("<group-id>/claims-triage-agent/1.0.0")
print(agent.endpoint_url) # https://<gateway-host>/<instance-path>/The agent’s card is at endpoint_url + .well-known/agent-card.json. It raises
RegistryError in the same cases as resolve_mcp(), including a gateway URL
that is not https://, and like it sends no gateway credential. The immutable
handle is resolution-only. Use donkey.a2a.send() or stream()
with the Exchange reference to call the agent; that provisional surface is
offline-verified, not yet live-verified for successful gateway send/SSE.
Framework-native AgentHandle.as_tool() remains planned.
Reading an LLM asset’s metadata
donkey.registry.llm_metadata() is Live. It reads the
llm-metadata file of an llm asset version, an LLM proxy or a custom LLM
provider, and returns what it declares:
meta = await donkey.registry.llm_metadata("<group-id>/my-llm-provider/1.0.0")
if meta is not None:
print(meta.platform, meta.input_format, meta.models)LlmMetadata has platform, name, input_format, models (the model IDs)
and capabilities (the file’s object as published). The read is tolerant: it
ignores fields it does not know, and a field the file leaves out or sets to the
wrong type comes back as None or empty, never a guess. A DDK LLM proxy’s file
sets only platform. The read returns None for a version with no
llm-metadata file, and raises RegistryError when Exchange has no such
version. It needs read:exchange, and the file download carries no credential.
“Governed” is a computed predicate
Publication to Exchange says nothing about whether an asset is fronted by a
gateway, has policies applied, or passes the org’s rulesets — there is no single
boolean to query. “Governed” is computed by joining state across systems,
and it is environment-scoped: an asset governed in Production may be
ungoverned in Sandbox. GovernanceCriteria makes every condition explicit. The
stricter preset, STRICT, is in donkey_kit.experimental:
from donkey_kit import GovernanceCriteria
from donkey_kit.experimental import STRICT
@dataclass(frozen=True)
class GovernanceCriteria:
require_api_instance: bool = True # an API Manager instance exists in this env
require_deployed: bool = True # deployed to a gateway, not just configured
require_any_policy: bool = True # at least one policy applied
required_policies: list[str] = ... # e.g. ["client-id-enforcement"]
forbidden_policies: list[str] = ...
require_governance_pass: bool = False # every API Governance report is Conformant
require_gateways: list[str] = ... # only assets behind these named gateways
require_tags: list[str] = ...
require_lifecycle: list[str] = ... # e.g. ["published", "approved"]
allow_unknown: bool = False # if a check can't be evaluated, does it pass?
# A ready-made strict preset:
STRICT = GovernanceCriteria(
require_governance_pass=True,
required_policies=["client-id-enforcement"],
allow_unknown=False,
)Pass it straight through:
tools = await donkey.tools.discover(governed=STRICT)allow_unknown matters more than it looks. If the platform doesn’t expose,
say, ruleset results, then require_governance_pass=True with
allow_unknown=False filters the whole catalog to zero — so every
filtered-out asset carries a reason, surfaced by explain().
explain() — why a tool was included or excluded
donkey.registry.explain() is Live. Without it,
governed=True returning an empty list is indistinguishable from a broken
credential. explain() reports every check the criteria turn on:
report = await donkey.registry.explain(
"<group-id>/sku-lookup-mcp/1.1.0", criteria=STRICT
)
# GovernanceReport(governed=False, checks=[
# Check("api_instance_exists", True, "instances sku-lookup in environment 'Sandbox'"),
# Check("deployed", True, "deployed: sku-lookup"),
# Check("any_policy", True, "a policy on each"),
# Check("required_policies", False, "sku-lookup is missing client-id-enforcement"),
# Check("governance_pass", None, "UNKNOWN: no governance profile has evaluated <group-id>/sku-lookup-mcp/1.1.0"),
# ])
print(report.reasons_failed())Each check is True (passed), False (failed, with the reason), or None
(couldn’t be evaluated, resolved by allow_unknown). When discover() keeps
no server, it logs why at info level, pointing you to explain().
It reads the asset version’s API Manager instances in the environment set by
ANYPOINT_ENV, and only what the criteria ask about:
| Check | Criteria | Passes when |
|---|---|---|
api_instance_exists | require_api_instance | the version has an API Manager instance in the environment |
deployed | require_deployed | at least one instance is deployed to a gateway |
any_policy | require_any_policy | every deployed instance has a policy |
required_policies | required_policies | every deployed instance has each named policy |
forbidden_policies | forbidden_policies | no deployed instance has a named policy |
gateways | require_gateways | every deployed instance is on a named gateway |
tags | require_tags | the Exchange asset version has each tag, ignoring case |
lifecycle | require_lifecycle | the version’s Exchange status is one of those named |
governance_pass | require_governance_pass | every API Governance report for the version is Conformant |
- Policies are matched by their asset ID, such as
client-id-enforcement, and gateways by name. - A version with no deployed instance fails the policy and gateway checks.
governance_passreads the reports of the business group’s API Governance profiles, retaining every report even when ruleset labels repeat. AnyNonConformantreport makes itFalse; it isTrueonly when every report isConformant. It is UNKNOWN when no profile has evaluated the version, when a report is pending or failed, or when the read is refused. API Governance evaluates an asset version when it is published, so a profile created later does not report on it.- A refused Exchange read makes
tagsandlifecycleUNKNOWN. A refused API Manager read raisesRegistryError. - Results are cached per asset version and criteria, like the other registry lookups; see Registry caching.
Defaults and performance
- Governed by default.
governeddefaults toTrue, so the set holds only the servers that pass the defaultGovernanceCriteria, and you can bind it as a whole. Each server it leaves out is logged with its failed checks. - Unfiltered is listed, not bindable.
governed=Nonelists every MCP server, and the first unfiltered call logs that discovery is unfiltered. It still lists a server the gateway does not govern, with itsexplain()report on the handle (McpServerHandle.governance), so you can audit the catalog. Binding refuses such a set withUngovernedMcpServer(see Only governed servers are bound). - Nothing found is not an error. When no server is left,
discover()returns an emptyToolSetand logs why: no MCP asset matched, or none was governed. - Cached, with a staleness check. A discovery is cached for
registry_cache_ttl_sseconds (default 300), per environment, tags and criteria.ToolSet.discovered_atsays when the registry was read andToolSet.is_staleturns true once the TTL has passed. When the entry expires, the nextdiscover()reads the registry again rather than the registry’s own cached lookups, so a verdict is never more than one TTL old.donkey.tools.refresh()drops the cached discoveries and the registry’s cachedsearch(),explain()andresolve_mcp()lookups, so the nextdiscover()reads the governance verdicts from API Manager again.DONKEY_NO_CACHE=1turns both caches off. Each call records adonkey.tools.discoverspan whosedonkey.discover.cacheattribute ishitormiss(see Telemetry). - No connection.
discover()opens no MCP connection. The tools are listed when you bind, or calldescribe(). - Bounded fan-out. The
explain()andresolve_mcp()reads for each asset run at most eight at a time. - Warm the cache at startup.
await donkey.tools.warm(...)takes the samedomain,tagsandgovernedarguments asdiscover(), does the same reads and fills the same cache entry, so the first matchingdiscover()does not wait on the registry. It always reads: it drops the registry’s cached lookups first, asdonkey.registry.refresh()does, so the verdicts it caches are current. It returns how many servers it cached. Anypoint has no bulk read of applied policies, so the cost grows with the catalog: one search, then oneexplain()per MCP asset. Measured at about 20 policy reads a second, 200 servers take roughly 10 seconds cold.
await donkey.tools.warm(tags=["erp"])
tools = await donkey.tools.discover(tags=["erp"]) # cache hitRelated
- Framework binding — turn a
ToolSetinto native tools. - Pinning & lockfile — pin each server’s listed tools and fail on drift.