mcp-openapi

mcp-openapi is a server based on the Model Context Protocol (MCP) that loads and serves multiple OpenAPI specifications, thereby supporting LLM-driven IDE integration and acting as a bridge between OpenAPI specifications and LLM development tools such as Cursor.

Key capabilities

• Load multiple OpenAPI specifications from a directory
• Expose API operations and schemas through the MCP protocol
• Enable LLMs to understand and use your API directly in the IDE
• Support dereferenced schemas to obtain complete API context
• Maintain a catalog of all available APIs

Powered by ReAPI. This open-source MCP server is sponsored by ReAPI, a next-generation API platform that simplifies API design and testing. This server provides local OpenAPI integration for development, while ReAPI provides two powerful modules: first, designing APIs with an intuitive no-code editor, automatically generating and publishing OpenAPI specifications, collaborating with team members in real time, version control, and change management; second, a developer-friendly no-code API testing solution, including an intuitive interface for creating and managing test cases, powerful assertion and validation capabilities, and a serverless cloud test runner, suitable for QA teams and developers, with CI/CD integration support. Try ReAPI for free at reapi.com.

Cursor configuration There are two configuration locations to choose from.

Option 1: Project-level configuration (recommended). Create a .cursor/mcp.json file in the project directory. This option is recommended because it allows different specification sets to be maintained for different projects. Tip: Using a relative path such as ./specs makes the configuration portable and easy for team members to share. Note: Using the @latest tag is recommended because the server is frequently updated with new features and improvements. Important: Project-level configuration helps manage LLM context limits. When all specifications are placed in a single folder, the combined metadata may exceed the LLM's context window, causing errors. Organizing specifications by project keeps the context size manageable.

Option 2: Global configuration. Create or edit ~/.cursor/mcp.json in the home directory to make the server available in all projects.

Enable in Cursor settings After adding the configuration: open the Cursor IDE; go to Settings > Cursor Settings > MCP; enable the @reapi/mcp-openapi server; click the refresh icon next to the server to apply changes. Note: by default, Cursor requires confirmation for every MCP tool execution. If you want to allow automatic execution without confirmation, you can enable Yolo mode in Cursor settings.

The server is now ready to use. After you add new OpenAPI specifications to the directory, you can refresh the catalog by opening Cursor's chat panel and entering one of the following prompts: "Please refresh the API catalog" or "Reload the OpenAPI specifications".

OpenAPI specification requirements Place OpenAPI 3.x specifications in the target directory: JSON and YAML formats are supported; files should have a .json, .yaml, or .yml extension; the scanner will automatically discover and process all specification files.

Specification ID configuration: by default, the file name (without the extension) is used as the specification ID. To specify a custom ID, add x-spec-id to the OpenAPI info object.

Important: when processing multiple specifications with similar or identical endpoint paths, the same schema names, or overlapping operation IDs, setting a custom x-spec-id is critical. Specification IDs help distinguish these similar resources and prevent naming conflicts.

How it works The server scans OpenAPI specification files in the specified directory; processes and dereferences the specifications to obtain full context; creates and maintains a catalog of all API operations and schemas; exposes this information through the MCP protocol; IDE integration can then use this information to: provide API context for LLMs, enable intelligent code completion, assist with API integration, and generate API-aware code snippets.

Tools (MCP tools)

• refresh-api-catalog: refresh the API catalog. Returns: a success message when the catalog refresh succeeds.
• get-api-catalog: get the API catalog. The catalog contains metadata for all OpenAPI specifications and their operations and schemas. Returns: the complete API catalog containing all specifications, operations, and schemas.
• search-api-operations: search operations across specifications. Input: query (string): the search query; specId (optional string): theSpecific API specification ID. Returns: matching operations from the API catalog.
• search-api-schemas: Search schemas across specifications. Input: query (string): search query; specId (optional string): the specific API specification ID to search within. Returns: matching schemas from the API catalog.
• load-api-operation-by-operationId: Load an operation by operationId. Input: specId (string): API specification ID; operationId (string): the operation ID to load. Returns: full operation details.
• load-api-operation-by-path-and-method: Load an operation by path and method. Input: specId (string): API specification ID; path (string): API endpoint path; method (string): HTTP method. Returns: full operation details.
• load-api-schema-by-schemaName: Load a schema by schemaName. Input: specId (string): API specification ID; schemaName (string): the schema name to load. Returns: full schema details.

Planned capabilities (listed as to-be-implemented in the materials)

• Semantic search: Enable natural language queries for API operations and schemas; improve search accuracy through semantic understanding.
• Remote specification synchronization: Support synchronizing OpenAPI specifications from remote sources.
• Code templates: Expose code templates through the MCP protocol; provide reference patterns for LLM code generation.
• Community contributions: Submit feature requests and bug reports; participate in improving the server.

Example prompts in Cursor Explore available APIs: "Show me all available APIs in the catalog with their operations" "List all API specifications and their endpoints" API operation details: "Show me the details of the create pet API endpoint" "What are the required parameters for creating a new pet?" "Explain the response schema for the pet creation endpoint" Schemas and mock data: "Generate mock data for the Pet schema" "Create a valid request payload for the create pet endpoint" "Show me examples of valid pet objects based on the schema" Code generation: "Generate an Axios client for the create pet API" "Create a TypeScript interface for the Pet schema" "Write a React hook that calls the create pet endpoint" API integration assistance: "Help me implement error handling for the pet API endpoints" "Generate unit tests for the pet API client" "Create a service class that encapsulates all pet-related API calls" Documentation and usage: "Show me example usage of the pet API with curl" "Generate JSDoc comments for the pet API client methods" "Create a README section explaining the pet API integration" Validation and types: "Generate Zod validation schema for the Pet model" "Create TypeScript types for all pet-related API responses" "Help me implement request payload validation for the pet endpoints" API search and discovery: "Find all endpoints related to pet management" "Show me all APIs that accept file uploads" "List all endpoints that return paginated responses"

These prompts demonstrate how to leverage the MCP server's capabilities for API development, and can be adjusted or combined according to specific needs to accomplish more complex tasks.

Contributing Contributions are welcome! Please submit a Pull Request.