OpenAPI → MCP: a practical guide

How to turn an existing OpenAPI spec into something an AI agent can use safely — without rewriting your API.

A valid OpenAPI document tells a developer how every endpoint behaves. An agent needs something different: a small set of clearly described, safely scoped capabilities it can select from at runtime. The gap between those two is where most APIs lose agent-readiness points.

1. Curate capabilities, don’t expose raw CRUD

An API with 300 low-level endpoints overwhelms tool selection. Group related operations into a dozen or so high-level capabilities that map to what an agent actually wants to do.

2. Write descriptions for selection, not reference

Every operation needs a one-line statement of intent. Empty or boilerplate descriptions are the single most common reason agents call the wrong tool.

3. Make the API discoverable

Publish an llms.txt, an OpenAPI document, or an MCP manifest so agents can find your capabilities at runtime rather than guessing from URLs.