Keep OpenAPI as the source of truth and treat the MCP server as a derived artifact — that is the right architecture, and it is the approach I have actually built. Generating from the contract means the tool definitions cannot drift from the API, and it keeps you from maintaining two descriptions of the same thing.
But generation is not the same as dumping. Tools are not endpoints. A tool is a task a consumer wants to accomplish, described in language a model can reason about. Most APIs have far fewer genuine tasks than they have operations, and the mapping is rarely one to one — one task might be three calls, and forty of your operations might not belong on the agent surface at all.
The failure mode is common and predictable: point a generator at a large OpenAPI, produce hundreds of tools, watch the agent pick the wrong one constantly, conclude that agents do not work. What actually happened is that nobody did the design work.
So: curate the set. Name tools for outcomes. Write descriptions for a model rather than for a changelog. Use the workflow-shaped operations where an outcome takes several steps. And govern the result — MCP does not escape any of the fundamental problems of APIs. It still needs discovery, documentation, versioning, security, and support.
