Tools

Package tools is everything your org can call, in one list: connector actions, functions, agents, skills and your own MCP servers.

tools

GetActivation reports which tools are switched on for the caller's org and project.

GET /v1/tools/activation

GetActivation reports which tools are switched on for the caller's org and project. Activation is what makes a tool dispatchable and what makes it visible to an agent, so this is the set the MCP tool list is drawn from — every other tool in the registry is discoverable but refused at call time.

PutActivation switches tools on and off for the caller's org and project, and answers with the resulting activated set.

PUT /v1/tools/activation

PutActivation switches tools on and off for the caller's org and project, and answers with the resulting activated set. It is the ONE write path that turns skills, plugins and connectors into callable tools — an unactivated tool is listed by discovery but refused 403 at dispatch. Activate is applied before Deactivate, so a name in both lists ends up off. More than 256 toggles in one request is refused 413.

Request body — application/json (required)

CallTool runs one of the caller's activated tools and answers with its output.

POST /v1/tools/call

CallTool runs one of the caller's activated tools and answers with its output.

This is the door onto the tool plane's DYNAMIC half — the half no build-time catalogue can hold, because it is per-tenant: an org's connected connector actions, its authored skills, its agents and functions, and the tools of every external MCP server it registered. A tool's existence, its price and its activation are all rows, not code, so they cannot be known until the caller is.

One policy, the registry's: resolve by precedence, refuse an unactivated tool 403, settle a priced one through the x402 seam or fail closed 402, then dispatch to the winning source bound to the caller's own (org, project). One metered unit, one audit record. A caller can only ever dispatch its own tools.

Discovery is GET /v1/tools — ?activated=true for the callable set.

Request body — application/json (required)

GetListing returns one catalog entry in full: the publisher's description, its repository and site, every package form with the runtime that launches it, and every hosted endpoint.

GET /v1/tools/catalog/{id}

GetListing returns one catalog entry in full: the publisher's description, its repository and site, every package form with the runtime that launches it, and every hosted endpoint. It is what a branding page renders, and what tells a caller whether the listing can be enabled here and now (a streamable-http remote) or needs somewhere to run first (a stdio package).

A HIDDEN listing is not served to an org — a shelf that renders what it does not list would be a way around the shelf — but is served to a SuperAdmin, who is the one deciding whether to put it back.

CurateListing sets what WE say about one catalog entry — hidden, featured, official, logo — and answers with the stored listing.

PATCH /v1/tools/catalog/{id}

CurateListing sets what WE say about one catalog entry — hidden, featured, official, logo — and answers with the stored listing. SuperAdmin only; every other caller is refused.

Curation is the half of a catalog row a sync cannot write, and this is the only thing that writes it. The upstream half is never editable here: a description that disagreed with the publisher's would be a fork of their listing, and the next sync would silently undo it.

Request body — application/json (required)

SyncCatalog pulls the public MCP registry into our canonical copy and reports what changed.

POST /v1/tools/catalog/sync

SyncCatalog pulls the public MCP registry into our canonical copy and reports what changed. SuperAdmin only; every other caller is refused.

It is IDEMPOTENT: a listing is keyed by the publisher's own reverse-DNS name, so a second pass over an unchanged registry rewrites the same rows and reports added=0, updated=0. It never deletes — a listing that vanishes upstream may be one an org has already enabled, and dropping its description would not drop its server. And it never touches CURATION: hidden, featured, an admin-set official and a logo survive every sync, because the write does not name those columns.

ListCatalog lists the MCP servers the public registries publish, as we hold them: our canonical copy of registry.modelcontextprotocol.io, plus what we decided about each entry.

GET /v1/tools/catalog

ListCatalog lists the MCP servers the public registries publish, as we hold them: our canonical copy of registry.modelcontextprotocol.io, plus what we decided about each entry.

This is the SHELF an org picks from. A listing with a streamable-http endpoint can be enabled as-is — POST /v1/mcp/servers with its id — and its tools then join the org's tool plane and the fleet's MCP door. A listing that only ships a stdio package needs a process to run it, which is why the transports are on every entry rather than implied.

Hidden entries are absent: they are the ones we took off the shelf. A platform SuperAdmin sees them, because the same query answers "what is on the shelf" and "what is in the catalog" and two queries would drift apart.

It is PAGED — 50 by default, 200 at most. The public registry publishes tens of thousands of servers, so an unbounded answer is a twenty-megabyte response and a storefront that renders in a minute. total is the whole match, not the page.

ListTools lists every tool the caller's org and project can reach, from every source, each flagged with whether it is activated.

GET /v1/tools

ListTools lists every tool the caller's org and project can reach, from every source, each flagged with whether it is activated. This is the discovery surface: one flat set of names spanning connector actions, user functions, zap-service routes, agents, skills and the org's own external MCP servers, deduplicated by name so the highest-precedence source wins a collision. It lists; it does not call — dispatch is POST /v1/tools/call.

---

All Hanzo APIs · Interactive reference