OpenAPI

You learn how to run and use the OpenAPI Search MCP Server to load OpenAPI specifications, explore endpoints, and query API data efficiently from MCP clients. It supports multiple OpenAPI versions, JSON and YAML formats, fast lookups, and both STDIO ( Claude Desktop style) and HTTP connections for flexible integration.

How to use

Operate the server as an MCP provider so your client can load OpenAPI documents, browse paths and operations, search endpoints, and inspect models and authentication information. You can either run the server locally and connect via STDIO or expose an HTTP endpoint for remote clients. Use a CLI workflow to load APIs, then progressively query for paths, operations, schemas, tags, and auth details. If you want to integrate with Claude Desktop, configure it to reach the HTTP endpoint or use a STDIO workflow that launches the Python runtime in your chosen environment.

How to install

# Prerequisites: ensure Python 3.12+, and a compatible environment manager

# Option A: Conda (recommended)
conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

# Install dependencies
pip install -r requirements.txt

# Run the server (STDIO mode) for Claude Desktop or local use
python main.py

# Optional: run in HTTP mode (standalone) - see instructions under HTTP mode

Additional sections

Configuration and runtime options are provided to let you run the server in the way that fits your setup. You can choose STDIO for local, Claude Desktop-style usage or HTTP for a standalone MCP endpoint. The HTTP port defaults to 8848 but can be customized through code or environment settings.

Explicit MCP connection options shown for Claude Desktop integration include both STDIO and HTTP configurations. Use these snippets directly to connect your client to the server.

{
  "mcpServers": {
    "openapi-search": {
      "url": "http://localhost:8848"
    }
  }
}

Notes on deployment and usage

The server supports multiple API documents loaded by name. It stores data in memory for fast access, and supports OpenAPI 3.0.x, 3.1.x, and Swagger 2.0. Formats (JSON and YAML) are auto-detected. You can load multiple versions of the same API by giving each a distinct name, and loading a new document with the same name will overwrite the existing one.

Typical workflows involve loading an API, listing its tags, exploring endpoints by tag, retrieving full path details, and inspecting data models or authentication information.

Troubleshooting and tips

If documents disappear after a restart, remember they are stored in memory only and must be reloaded. For Claude Desktop users, ensure the configuration points to the correct HTTP endpoint or use the provided STDIO command to launch the server within the desired environment.

Available tools

load_openapi

Load an OpenAPI document from a URL and store it in memory for subsequent queries.

list_apis

List all loaded APIs with basic information such as name, title, version, and path count.

get_path_details

Return complete documentation for a specific API path, including methods, parameters, and responses.

list_all_paths

List all paths for a given API along with supported HTTP methods per path.

get_operation_by_id

Fast lookup of an operation by its operationId, returning path and method details.

search_endpoints

Search endpoints by keyword, HTTP method, and/or tag to filter results.

list_tags

List all tags defined in an API with their descriptions.

get_endpoints_by_tag

Retrieve all endpoints associated with a specific tag.

get_schema_details

Extract a data model schema from components/schemas by name.

get_auth_info

Display authentication schemes and global security requirements.