mcp-openapi is an MCP server designed to streamline LLM-powered IDE integrations. It acts as a bridge, loading and serving multiple OpenAPI specifications to development tools like Cursor, enabling intelligent code completion and API understanding.

This server empowers LLMs within IDEs to directly interact with and comprehend your APIs. It achieves this by exposing API operations and schemas through the MCP protocol, supporting dereferenced schemas for complete API context. Key features include automatic discovery of OpenAPI files (JSON/YAML), customizable specification IDs, and a maintained catalog of available APIs.

By integrating mcp-openapi, developers can leverage LLMs to generate API-aware code snippets, assist in API integration, and provide intelligent code completion, significantly accelerating development workflows and reducing integration complexities. It seamlessly integrates with Cursor via project-specific or global configurations.

OpenAPI Specification Loading

The core function of mcp-openapi is its ability to load multiple OpenAPI specifications from a designated directory. It automatically scans for .json, .yaml, and .yml files, parsing them into a unified API catalog. This eliminates the need for manual API definition management within the IDE, streamlining the integration of various APIs into the development workflow. The server dereferences specifications, resolving external references to provide a complete API context to the LLM. This ensures that the LLM has all the necessary information to understand and interact with the APIs effectively.

Example: A developer working on a microservices architecture can point mcp-openapi to a directory containing OpenAPI specifications for each service. The server automatically loads and catalogs all the APIs, allowing the LLM to understand the relationships and interactions between the services.

Technical Detail: The server uses file system monitoring to detect changes in the specification files, automatically reloading the API catalog when updates are detected.

API Catalog and Discovery

mcp-openapi creates and maintains a comprehensive catalog of all API operations and schemas derived from the loaded OpenAPI specifications. This catalog serves as a central repository of API metadata, enabling developers to easily discover and understand available APIs. The catalog is exposed through the MCP protocol, allowing IDE integrations to query and retrieve information about specific APIs, operations, or schemas. This feature significantly enhances API discoverability, especially in projects with a large number of APIs.

Example: A developer can use the "search-api-operations" tool to find all API operations related to user authentication across multiple services. The server returns a list of matching operations, along with their descriptions and parameters, enabling the developer to quickly identify the relevant APIs.

Technical Detail: The API catalog is indexed and optimized for fast searching, ensuring that IDE integrations can quickly retrieve API information without impacting performance.

LLM-Powered IDE Integration

mcp-openapi acts as a bridge between OpenAPI specifications and LLM-powered development tools, such as Cursor. By exposing API information through the MCP protocol, it enables LLMs to understand and interact with APIs directly within the IDE. This allows developers to leverage LLMs for tasks such as code completion, API integration, and code generation, significantly improving their productivity. The integration allows LLMs to provide context-aware suggestions and generate code snippets that are tailored to the specific APIs being used.

Example: A developer can ask the LLM to generate an Axios client for a specific API endpoint. The LLM uses the information from the API catalog to generate the client code, including the correct method, parameters, and data types.

Technical Detail: The server supports the MCP protocol, allowing IDE integrations to communicate with the server and retrieve API information in a standardized format.

Custom Specification ID

The x-spec-id extension allows developers to assign unique identifiers to their OpenAPI specifications. This is particularly useful when working with multiple specifications that have similar or identical endpoint paths, schema names, or operation IDs. By setting a custom x-spec-id, developers can disambiguate between different APIs and ensure that the LLM can accurately identify and interact with the correct API. This feature is crucial for maintaining clarity and avoiding conflicts in complex API environments.

Example: Two different services, "user-service" and "admin-service," both have a /users endpoint. By setting x-spec-id to "user-service" and "admin-service" respectively, developers can reference these endpoints specifically as user-service/users and admin-service/users.

Technical Detail: The server reads the x-spec-id from the OpenAPI specification and uses it as the unique identifier for the API in the catalog.

Tools for API Interaction

mcp-openapi provides a set of tools that allow developers to interact with the API catalog and retrieve specific API information. These tools include "refresh-api-catalog," "get-api-catalog," "search-api-operations," "search-api-schemas," "load-api-operation-by-operationId," "load-api-operation-by-path-and-method," and "load-api-schema-by-schemaName." These tools enable developers to programmatically access and manipulate API metadata, facilitating tasks such as API discovery, code generation, and documentation.

Example: A developer can use the "load-api-operation-by-operationId" tool to retrieve the complete details of a specific API operation, including its parameters, request body, and response schema. This information can then be used to generate code or documentation for the API.

Technical Detail: The tools are implemented as MCP endpoints, allowing IDE integrations to invoke them using the MCP protocol.