Lessons from complex OpenAPI spec to MCP server conversions

Stainless has developed a method for transforming OpenAPI specifications into MCP servers, enabling clients to expose their APIs as tools for large language models (LLMs). While the process initially seemed straightforward due to both OpenAPI and MCP using JSON Schema, complexities arose in mapping request bodies, path parameters, and handling naming collisions, as well as managing $refs and recursive references. To address these challenges, Stainless leveraged its experience in SDK generation, creating best practices for MCP server implementation. They also introduced capabilities like tool selection to manage large APIs, and transformations to accommodate varying client schema limitations, ensuring compatibility with different MCP clients. This dynamic approach allows users to import, customize, and manage tools flexibly, with the option to tweak or extend server functionalities. Looking forward, Stainless aims to refine its implementation to keep pace with advances in remote MCP servers and LLM capabilities.