OpenAPI as an agent surface
OpenAPI as an agent surface, maintained by OpenAPI Initiative (spec); each vendor for its own file. A machine-readable description of an HTTP API that agents and tool generators read to call endpoints without an MCP server. Status: OpenAPI 3.x in wide use; agents.json and Kong's AI MCP Server build on it.
Fact sheet
| Name | OpenAPI as an agent surface |
|---|---|
| Maintainer | OpenAPI Initiative (spec); each vendor for its own file |
| What it is | A machine-readable description of an HTTP API that agents and tool generators read to call endpoints without an MCP server. |
| Status and version | OpenAPI 3.x in wide use; agents.json and Kong's AI MCP Server build on it. |
| What it does not do | Does not carry agent auth flows or tool descriptions written for models; agents must find the file, usually through a link. |
Dated facts
- Ora's lab found (AgentReady launch post, 19 Oct 2026) that agents reached openapi.json in 21 percent of traced runs on sites that ship one, and 97 percent of those fetches arrived through a link, not a guessed path. (ora.ai, dated 19 October 2026, read 4 November 2026)
- AgentReady.org lists a public API with OpenAPI as a SHOULD for the act layer, next to the MUST of an MCP server or a CLI. (ora.ai, dated 19 October 2026, read 4 November 2026)
- Kong's AI MCP Server entity turns existing APIs into MCP tools. (developer.konghq.com, read 4 November 2026)
- agents.json is defined as an extension of OpenAPI. (github.com, read 4 November 2026)
- Stripe's MCP server exposes API methods through stripe_api_read and stripe_api_write rather than one tool per endpoint. (docs.stripe.com, read 4 November 2026)
Seen in the shared crawl
| Path | Top 10,000 found | Ora leaderboard found |
|---|---|---|
/openapi.json | 21 of 7,472 (0.28%) | 78 of 3,369 (2.32%) |
/openapi.yaml | 10 of 7,503 (0.13%) | 22 of 3,378 (0.65%) |
A path counts only when the answer is the right kind of document. Many sites answer these paths with an ordinary web page, which is not counted. See the census.