MCP OpenAPI Server

You can load multiple OpenAPI specifications into a single MCP server to power LLM-assisted IDE integrations. This server collects API operations and schemas, makes them available through the MCP protocol, and keeps a searchable catalog so your development tooling can understand and generate API-aware code.

How to use

You integrate the MCP OpenAPI server with your IDE or tooling client to empower API-aware development. The server exposes all loaded specifications and their schemas, enabling features like API context for LLMs, intelligent code completion, and code generation helpers. You can refresh the catalog after adding new specifications so your IDE sees the latest API surface.

How to install

Prerequisites you need before starting:

• Node.js and npm or npx available on your system
• Access to the directory containing your OpenAPI specs (JSON or YAML)

Step-by-step commands to set up the MCP OpenAPI server for local use with Cursor (recommended project-specific setup):

# Ensure you are in your project directory
# Install the MCP OpenAPI server as a dev dependency (or run directly with npx)
# Here we initialize Cursor to run the MCP server from the project scope

How to install

Option 1: Project-specific configuration (recommended). Create a Cursor project config that runs the MCP server from your project. You specify the directory that contains your OpenAPI specs.

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
      "env": {}
    }
  }
}

How to install

Option 2: Global configuration makes the server available across all projects. Extend your home Cursor config to point at your specs directory.

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
      "env": {}
    }
  }
}

Configuration and usage notes

OpenAPI specifications must be placed in your target directory in JSON or YAML format. The server discovers all files with .json, .yaml, or .yml extensions. Each specification uses its filename as the default spec ID, or you can assign a custom ID by adding x-spec-id in the OpenAPI info section.

If you work with multiple specifications that have overlapping paths, schemas, or operation IDs, set a custom spec ID to distinguish them. Example: use user-service for one spec and admin-service for another, so endpoints like /users are unambiguous when referenced.

OpenAPI specification requirements

• Place your OpenAPI 3.x specifications in the target directory (JSON or YAML)
• Files must use .json, .yaml, or .yml extensions
• The server automatically discovers all specification files

Specification ID configuration: use the filename as the default spec ID or define x-spec-id in the info object to set a custom ID.

How it works

The server scans the designated directory for OpenAPI specs, dereferences them for complete context, builds a catalog of all API operations and schemas, and exposes this information via the MCP protocol. IDE integrations can then provide API context to LLMs, enable code completion, assist in API integration, and generate API-aware code snippets.

Tools

Use the following actions to manage and query the API catalog from your MCP-enabled environment.

• refresh-api-catalog — Refresh the API catalog and get a success message on completion
• get-api-catalog — Retrieve the complete API catalog including specs, operations, and schemas
• search-api-operations — Find operations across the catalog with an optional spec filter
• search-api-schemas — Find schemas across the catalog with an optional spec filter
• load-api-operation-by-operationId — Load full details for a specific operation by its operationId
• load-api-operation-by-path-and-method — Load operation details by endpoint path and method
• load-api-schema-by-schemaName — Load a schema by its schemaName

Prompts and usage examples in Cursor

Explore available APIs, request operation details, generate code, and validate payloads using natural language prompts in Cursor.

Available tools

refresh-api-catalog

Refreshes the API catalog to reflect any changes in the loaded specifications.

get-api-catalog

Returns the complete API catalog with all specifications, operations, and schemas.

search-api-operations

Searches for operations across specifications, with an optional specId to limit scope.

search-api-schemas

Searches for schemas across specifications, with an optional specId to limit scope.

load-api-operation-by-operationId

Loads full details for a specific operation using its operationId.

load-api-operation-by-path-and-method

Loads full details for an operation by its path and HTTP method.

load-api-schema-by-schemaName

Loads full details for a schema by its schemaName.