mcp-openapi

The @reapi/mcp-openapi server loads and serves multiple OpenAPI specifications from a directory and exposes their API operations and schemas through the MCP protocol. It dereferences OpenAPI schemas for complete API context and builds a catalog of all available specifications, operations, and schemas so that IDEs and LLM-powered tools can access API context directly within your development environment. This enables features like API-aware code completion, contextual prompts for LLMs, and streamlined discovery of operations across multiple specifications. Tools exposed by the server include capabilities to refresh and inspect the catalog, search for operations and schemas across specs, and load detailed operation or schema data by various identifiers, making it easy to integrate OpenAPI docs into Cursor or other MCP-enabled IDEs.

To use it with Cursor, configure the MCP server in your project (project-specific) or globally. Once connected, you can refresh the API catalog after adding or updating OpenAPI files, query for available operations, and load specific operation details to feed context to your LLMs or code generation tools. The server supports multiple specs in a single directory, and you can differentiate them using the x-spec-id field in each OpenAPI document to avoid naming conflicts when combining endpoints from different APIs.

Prerequisites:

• Node.js (recommended LTS, e.g., 18.x or newer) and npm installed on your system
• Access to a directory with OpenAPI 3.x specifications (JSON or YAML)

Installation steps:

1. Ensure Node.js and npm are installed. Verify: node -v npm -v

2. Prepare your OpenAPI specs in a directory (for example, ./specs). Each file can be JSON or YAML; you can use x-spec-id in the OpenAPI info to assign a custom spec ID when multiple specs share paths or component names.

3. Run the MCP OpenAPI server via npx (no install required): npx -y @reapi/mcp-openapi@latest --dir ./specs

   The server will scan ./specs, load and dereference your OpenAPI documents, and expose them through MCP. If you prefer a project-wide configuration for Cursor, you can place a config snippet in .cursor/mcp.json as shown in the README example, which uses the same CLI invocation under the hood.

4. Optional: create a persistent global configuration for Cursor using the provided JSON format, and point the dir to your specs path.

Tips and notes:

• If you add new OpenAPI specs, you can refresh the catalog from your IDE (Cursor) or by restarting the MCP server with the same invocation.
• Use x-spec-id in your OpenAPI info to disambiguate specs that share similar endpoints or component names.
• The MCP server exposes commands such as refresh-api-catalog, get-api-catalog, search-api-operations, search-api-schemas, and loaders for operations and schemas. These can be invoked by clients to build context for LLM-based workflows.
• For large collections of specs, organize by project or module to prevent the collective context from exceeding LLM token limits.
• If you modify specs, ensure the JSON/YAML syntax remains valid and that any references are resolvable in the dereferenced context.
• Cursor users: enable Yolo mode if you want automatic execution of MCP actions without per-action confirmation (see Cursor docs).