OpenAPI AnyApi MCP Server for Claude Desktop

Overview

This MCP server lets Claude Desktop discover and call nearly any REST API described by an OpenAPI (Swagger) JSON. Instead of sending the entire spec to the assistant, the server semantically indexes the OpenAPI document (chunking by endpoint), embeds the chunks, and stores them in an in-memory FAISS index. When Claude issues a natural language query, the MCP server finds the most relevant endpoint docs instantly and provides the full parameter/response shape back to Claude so it can construct a correct request. A second tool on the server executes the HTTP request and returns the response.

This approach solves a common problem: large OpenAPI files overwhelm MCP clients or produce truncated/misunderstood tool descriptions. By doing endpoint-level semantic search and returning precise endpoint docs, Claude can pick the right API and build valid requests (including headers, path/query/body parameters).

Features

• Semantic endpoint discovery from a remote OpenAPI JSON (no local files required)
• Endpoint-level chunking to preserve full parameter context for each endpoint
• In-memory FAISS vector store for low-latency Top-K retrieval
• Lightweight MiniLM-L3 embedding model (optimized size) for embeddings
• FastAPI async server with two MCP-compatible tools:
  • _request_schema: returns endpoint docs / base URL
  • _make_request: executes the constructed HTTP request
  • Automatic base URL extraction from the OpenAPI spec, with optional override
  • Configurable tool namespace so you can register multiple MCP servers (finance, healthcare, etc.)

  How it works (high level)

  1. Server fetches the OpenAPI JSON from a URL and breaks it into endpoint chunks.
  2. Each chunk is embedded (MiniLM-L3) and indexed into FAISS.
  3. Claude Desktop queries the MCP tool for a purpose (e.g., “list products”); the server embeds the query and returns Top-K matching endpoint docs.
  4. Claude uses the returned schema to construct a valid HTTP request.
  5. Claude calls the server’s make_request tool to execute the request and the server returns the live response.

  Diagram (conceptual): query -> embeddings -> FAISS TopK -> endpoint docs -> Claude constructs request -> make_request -> response

  Installation / Configuration

  Run the Docker image and pass environment variables to configure source spec, prefixes, and prompts.

  Minimal example:

  docker run --rm -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
    -e MCP_API_PREFIX=example \
    -e GLOBAL_TOOL_PROMPT="Access to Example APIs for ExampleCorp." \
    buryhuang/mcp-server-any-openapi:latest
  

  Important environment variables:

  OPENAPI_JSON_DOCS_URL     # URL to OpenAPI JSON (required)
  MCP_API_PREFIX            # Tool namespace prefix (default: any_openapi)
  GLOBAL_TOOL_PROMPT        # Text prepended to tool descriptions (strongly recommended)
  API_REQUEST_BASE_URL      # Optional override for base URL extracted from spec
  

  Multi-instance JSON (Smithery or other orchestrators):

  {
    "mcpServers": {
      "finance_openapi": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
          "-e", "MCP_API_PREFIX=finance",
          "-e", "GLOBAL_TOOL_PROMPT=Access to finance APIs for ACME Inc.",
          "buryhuang/mcp-server-any-openapi:latest"
        ]
      },
      "healthcare_openapi": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json",
          "-e", "MCP_API_PREFIX=healthcare",
          "-e", "GLOBAL_TOOL_PROMPT=Access to healthcare APIs for MedThings.",
          "buryhuang/mcp-server-any-openapi:latest"
        ]
      }
    }
  }
  

  Available Tools

  When the server starts it registers two MCP-style tools using the prefix you provide:

  • {prefix}_request_schema
    • Purpose: discover relevant endpoints for a natural-language query.
    • Returns: base URL (extracted or overridden) and full endpoint docs (parameters, path, query, body schemas).
  • {prefix}_make_request
    • Purpose: execute an HTTP request constructed by the assistant following the schema.
    • Input: method, path, headers, query parameters, body.
    • Output: HTTP status, headers, response body.

  Default prefix example: if MCP_API_PREFIX=any_openapi, tools will be any_openapi_request_schema and any_openapi_make_request.

  Use Cases

  • Private API access in Claude Desktop: let Claude discover internal endpoints and form correct calls without uploading the whole OpenAPI file.
  • Rapid prototyping: ask the assistant to “create a new product” and it will find the POST /products endpoint, craft body and headers, then execute the request.
  • Multi-API orchestration: run multiple MCP server instances with different prefixes to expose multiple API surfaces to a single Claude Desktop workspace.
  • Debugging and exploration: query for “get customer by email” and immediately receive precise endpoint docs and example request shapes.

  Example Claude project prompt:

  Use tools financial_request_schema and financial_make_request.
  Get endpoint details from financial_request_schema. Then use financial_make_request to call it.
  Add header: Authorization: Bearer <token>
  The base URL is returned by financial_request_schema; you do not need to hardcode it.
  

  Example chat instruction: User: “List all active products” Assistant: (calls financial_request_schema -> receives endpoint docs) -> constructs request -> calls financial_make_request -> returns API response.

  Limitations & Notes

  • Cold start: loading embedding models can add a delay on first start (~10–20s depending on environment).
  • Docker image size: model assets increase image size if pre-bundled; there are build constraints and trade-offs.
  • Platform: some builds (e.g., linux/arm/v7) may fail due to underlying transformer library support.
  • Model download dependency: if the image relies on Hugging Face at runtime, the host must have network access; alternative images can include pre-downloaded models.

  Troubleshooting

  • If Claude cannot find the endpoint, ensure GLOBAL_TOOL_PROMPT clearly names the API scope and use descriptive assistant instructions.
  • Override API_REQUEST_BASE_URL when the OpenAPI servers block or differ from the runtime base URL.
  • Monitor logs for FAISS/embedding errors; missing model files or network failures during model download are common root causes.

  Repository / Source: https://github.com/baryhuang/mcp-server-any-openapi

  Tags:api-integrationfaissmcp servermcp-serveropenapisearchsemantic searchsemantic-search