Skip to Content
These docs describe donkey-kit v0.2.1. Release notes
Tool accessDiscovery, search & filter

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 )
ArgumentTypeMeaning
domainstr | NoneCatalog domain. Raises NotImplementedError for now: Exchange has no domain filter.
tagslist[str] | NoneAll listed tags must be present.
governedbool | GovernanceCriteria | NoneTrue (the default) applies the default criteria; pass a GovernanceCriteria (e.g. STRICT) for explicit rules; None = unfiltered.
lockedboolTrue reads donkey.lock and checks the set against it: drift raises ToolLockDrift, and unpinned tools are dropped (see Pinning & lockfile). Provisional. Default False.
lock_pathstr | PathLikeThe lockfile locked=True reads. Default "donkey.lock".
authMcpAuth | NoneThe 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.

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 query without *, ? or [ is matched by Exchange: whole words and word prefixes of the asset ID, name or description, ignoring case. "sku" and "look" find SKU Lookup MCP Server; "ku-loo" does not.
  • A query with *, ? 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 has limit matches.
  • asset_types and tags are 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 with donkey.registry.llm_metadata(). A tag is an Exchange tag.
  • domain, environment, governed and the "a2a-agent" type raise NotImplementedError for now. Exchange has no domain filter, and environment and governed need 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 RegistryError when 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 be https://. Plain http:// is accepted for a loopback host, and for any other host only with DONKEY_ALLOW_HTTP=1 in the environment, with a ConfigWarning. A gateway public URL that is not, or that carries a user name or password, raises RegistryError. discover() then lists the server with a failed resolve_mcp check, 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 governance is None: whether the instance is governed comes from explain().
  • 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:

CheckCriteriaPasses when
api_instance_existsrequire_api_instancethe version has an API Manager instance in the environment
deployedrequire_deployedat least one instance is deployed to a gateway
any_policyrequire_any_policyevery deployed instance has a policy
required_policiesrequired_policiesevery deployed instance has each named policy
forbidden_policiesforbidden_policiesno deployed instance has a named policy
gatewaysrequire_gatewaysevery deployed instance is on a named gateway
tagsrequire_tagsthe Exchange asset version has each tag, ignoring case
lifecyclerequire_lifecyclethe version’s Exchange status is one of those named
governance_passrequire_governance_passevery 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_pass reads the reports of the business group’s API Governance profiles, retaining every report even when ruleset labels repeat. Any NonConformant report makes it False; it is True only when every report is Conformant. 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 tags and lifecycle UNKNOWN. A refused API Manager read raises RegistryError.
  • Results are cached per asset version and criteria, like the other registry lookups; see Registry caching.

Defaults and performance

  • Governed by default. governed defaults to True, so the set holds only the servers that pass the default GovernanceCriteria, 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=None lists every MCP server, and the first unfiltered call logs that discovery is unfiltered. It still lists a server the gateway does not govern, with its explain() report on the handle (McpServerHandle.governance), so you can audit the catalog. Binding refuses such a set with UngovernedMcpServer (see Only governed servers are bound).
  • Nothing found is not an error. When no server is left, discover() returns an empty ToolSet and logs why: no MCP asset matched, or none was governed.
  • Cached, with a staleness check. A discovery is cached for registry_cache_ttl_s seconds (default 300), per environment, tags and criteria. ToolSet.discovered_at says when the registry was read and ToolSet.is_stale turns true once the TTL has passed. When the entry expires, the next discover() 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 cached search(), explain() and resolve_mcp() lookups, so the next discover() reads the governance verdicts from API Manager again. DONKEY_NO_CACHE=1 turns both caches off. Each call records a donkey.tools.discover span whose donkey.discover.cache attribute is hit or miss (see Telemetry).
  • No connection. discover() opens no MCP connection. The tools are listed when you bind, or call describe().
  • Bounded fan-out. The explain() and resolve_mcp() reads for each asset run at most eight at a time.
  • Warm the cache at startup. await donkey.tools.warm(...) takes the same domain, tags and governed arguments as discover(), does the same reads and fills the same cache entry, so the first matching discover() does not wait on the registry. It always reads: it drops the registry’s cached lookups first, as donkey.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 one explain() 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 hit
Last updated on