API discovery

How an AI agent discovers and works with your organisation's APIs through Spec0's authenticated MCP tools — the discovery loop, the questions it answers, and a worked example.

Once an agent is connected with a token, it can discover and use your organisation's APIs through the org-scoped MCP tools — with no hardcoded knowledge of your registry baked into the prompt. The agent asks Spec0 what exists, narrows to the right API and operation, and reads the exact contract. This page is the mental model.

The discovery tools are authenticated — they need a Bearer token (PAT or Service Account Token) and resolve strictly against that token's org. See Connect your agent.

The discovery loop

A typical sequence an agent works through, from "I don't know your APIs" to "I can call this exact endpoint":

whoami — confirm which org and identity the token resolves to.
list_apis — enumerate the org's indexed APIs (id, name, version, one-line summary).
search_apis(query) — semantic search across the org's specs to find the right API by intent ("the one that handles refunds"), not by exact name.
search_operations(apiId, query) — within one API, find the specific endpoint by natural-language query.
search_components(apiId, query) — within one API, find the schema/model definitions (request/response shapes).
get_operation(apiId, method, path) — the structured detail of one exact operation: parameters, request body, response codes.
get_api_spec(apiId, environment?) — the full OpenAPI spec (or a high-level overview when it's large) when the agent needs the whole contract. Pass an optional environment name (e.g. "staging", "production") to read the spec current in that environment; omit it for the API's latest.

Steps narrow from "which API?" to "which operation?" to "exact request shape" — so the agent reads only what it needs.

What you can ask

The tools map to the questions a developer (or their agent) actually asks. Each tool's MCP description tells the model when to reach for it, so you don't have to prompt-engineer tool selection.

You want to…	The agent calls
Find the API that does something	`search_apis("refunds")`
List everything your org publishes	`list_apis()`
Find a specific endpoint in an API	`search_operations(apiId, "issue a refund")`
Find a schema/model in an API	`search_components(apiId, "Refund")`
Read one operation's exact contract	`get_operation(apiId, method, path)`
Read a whole API spec	`get_api_spec(apiId)`
Read the spec current in an environment	`get_api_spec(apiId, "production")`
Check an API's quality / lint health	`get_api_health(apiId)`
See what changed between versions	`get_api_changelog(apiId)`
Find who owns an API	`get_api_owner(apiId)`
List a team's APIs	`search_apis_by_owner(teamId)`
Confirm caller identity / org	`whoami()`

The full input/return reference for every tool is on the Agents overview, generated from the live MCP server.

Insights, not just specs

Beyond raw contracts, two tools surface the same governance signals the dashboard shows:

get_api_health(apiId) returns the Spectral lint score, findings count, and last-lint time — so an agent can warn "this API scores 62/100, here are the issues" before you integrate against it. (Same score you configure under Governance.)
get_api_changelog(apiId) returns the change history — latest version, a specific version, or a diff between two — so an agent can tell you what moved between releases. (Same data as Versioning → Changelogs.)

Environment-aware specs

If an API uses environments, get_api_spec can return the spec current in a specific environment instead of the latest published version:

get_api_spec(apiId, "production") → the version promoted to production.
get_api_spec(apiId, "staging") → the version in staging.
Omit the environment (or pass one with no pinned version) → the API's latest spec.

So an agent can answer "what does production expose today?" distinctly from "what's the newest version?" — which matters when staging is ahead of production. This is an org-scoped, internal surface; the public registry and generated SDKs stay environment-less. See Environments.

Worked example

A developer asks their agent: "Which of our APIs handles refunds, and what do I send to issue one?"

search_apis("refunds") → finds payments-api with a citation URL into the dashboard.
search_operations("payments-api-id", "issue a refund") → surfaces POST /refunds.
get_operation("payments-api-id", "POST", "/refunds") → returns the request body schema, required fields, and response codes.
The agent writes the integration code against that exact shape and cites https://app.spec0.io/apis/<apiId> so you can verify.

No spec was pasted into the prompt; the agent pulled exactly what it needed, scoped to your org.

Scoping and safety

Org tools are strictly token-scoped: list_apis and search_apis return only the caller's org's APIs, and get_api_spec / get_operation reject ids the token's org doesn't own. The same isolation that protects the registry in the dashboard applies to the MCP surface — see APIs → Org boundaries.