OpenAPI is not docs. Stop shipping it to your AI agent.

Every team I talk to that's building "an MCP from our API" thinks they're done once they have an OpenAPI spec. They are not done. They've just finished step one of four.

An OpenAPI spec is a great machine-readable inventory. It tells you what exists. It doesn't tell the model when to use what. That gap is where AI agents fall apart.

Inventory ≠ instructions

Look at any decent SaaS API. You'll find dozens of routes that overlap:

POST   /users                   create a user
POST   /users/invite            invite a user
POST   /workspaces/:id/members  add to workspace
PUT    /memberships/:id         move between workspaces

A naive MCP exposes all four. The model picks one based on tokenised name similarity to your prompt. Half the time it picks wrong, and the failure mode is silent — it returns a 200 with the wrong user in the wrong workspace.

Workflows are the unit of usefulness

The doc2mcp pipeline groups routes into workflows: chains of calls that map to one human-intent. The four routes above become one tool:

onboard_user({ email, role, workspaceId }) {
  // POST /users
  // POST /workspaces/:id/members
  // returns { userId, membershipId }
}

The model now has one obvious choice for "add a teammate to our workspace". Failure rate collapses, because there's nothing adjacent to pick wrong.

Auth is part of the workflow, not a footnote

Most OpenAPI specs declare auth at the schema level and forget about it. We treat auth as the first step of every workflow. The tool's first call is to verify the token's scopes match the operation; if they don't, we return a structured error the model knows how to act on (refresh, escalate, or stop).

Versions are workflows too

When v2 of an API ships, the old workflow shouldn't vanish. It should be marked deprecated_in: 2.1.0, with a machine-readable migration block pointing at the new workflow. The MCP serves both for a grace period. Your agent fleet migrates gradually instead of all-at-once.

A small checklist before you ship

• Group overlapping routes into a single semantic tool, even if it's three HTTP calls underneath.
• Include the success criteria in the tool description, not just the parameters.
• Bake auth verification into the first step of every workflow.
• Mark deprecated routes with their replacement. Don't yank them.

OpenAPI tells the model what exists. doc2mcp tells the model what to do.