MCP Is an Adapter Layer, So Version the API First

MCP functions as a layer on top of an API, making it crucial to prioritize the API contract as the variable that could potentially cause issues. A recommended approach is to review changes in the following sequence: API surface (endpoints, required parameters, response fields, enums, authentication shape), MCP mapping (mapping of API fields to tool inputs/outputs), agent behavior (prompts, tool selection, retry logic, and error handling).

This order is important because MCP can make an integration appear stable even if the underlying API has already undergone changes. Such changes may initially go unnoticed in the MCP, only surfacing later as vague tool failures, poor completions, or agents choosing the incorrect path. To mitigate this, it is suggested to maintain an OpenAPI specification, compare it within the CI process, and manually categorize modifications as breaking or non-breaking before updating the MCP wrapper.

While this approach might suffice for smaller APIs with a narrow tool surface, it may not be adequate when numerous minor schema edits accumulate. The MCP layer may remain thin, but the review process can still be burdensome. The recommended practice is to first version and gate the API, and then proceed to regenerate or update the MCP adapter subsequently.

The most vexing break encountered in practice could stem from required fields changing, enum drift, authentication modifications, or something else occurring at the MCP-to-API boundary.