From OpenAPI spec to MCP: How we built Xata's MCP server

Summary

Model Context Protocol (MCP) is an emerging standard that lets AI models securely interact with tools and APIs in real time. Building an MCP server means exposing a set of “tools” (operations) that a Large Language Model (LLM) can call to perform tasks, for example, fetching data or triggering actions via your backend. Rather than hand-coding each tool, we set out to generate an MCP server from our existing OpenAPI specification, leveraging our API’s schema as a single source of truth. This OpenAPI-driven approach promises quick development and consistency, but it comes with design considerations.On one hand, auto-generating tools directly from a REST API spec is very appealing. You’ve already documented your API thoroughly, so why not transform those endpoints into AI-accessible functions? It saves time and keeps the API and MCP definitions in sync, avoiding duplicate work. On the other hand, a naïve one-to-one mapping of every endpoint to an MCP tool can overwhelm an LLM. LLMs struggle to choose the right action from so many low-level options, leading to frequent errors or unpredictable calls, especially if several endpoints have similar purposes.The solution lies in a balanced approach. Writing an MCP server entirely by hand for a large API would be a massive time sink, manually crafting each tool’s schema and handler is tedious and error-prone, especially when a well-defined OpenAPI spec already exists. Instead, we can autogenerate the groundwork from OpenAPI, then curate it. In practice, this means using codegen to produce a set of tool definitions and client calls, then trimming or augmenting the OpenAPI spec that generates the tools to align with real-world usage. This post is a technical overview of how we built the Xata MCP Server, covering our switch to a new OpenAPI codegen approach, custom generation of MCP tools, and the Next.js server implementation.We’ll walk through the journey in three parts:Migrating to Kubb for OpenAPI code generation. Why we repl...