MCP HubMCP Hub
baryhuang

mcp-server-any-openapi

by: baryhuang

mcp server any openapi

25created 09/02/2025
Visit
openapi

📌Overview

Purpose: The primary goal of MCP Server is to serve as a scalable OpenAPI endpoint discovery and API request tool that simplifies the interaction with large API documentation through semantic search.

Overview: MCP Server leverages advanced technologies to facilitate quick and efficient searching of API endpoints using natural language queries. It supports in-memory search capabilities and a structured approach to handle extensive OpenAPI documentation without loss of context.

Key Features:

  • Semantic Search: Utilizes an optimized MiniLM-L3 model for fast, in-memory semantic search, significantly reducing the overhead with a compact model size compared to traditional approaches.

  • Flexible Configuration: Allows easy integration with remote OpenAPI JSON files, enabling automatic updates and a customizable tool namespace via environment variables.

  • Async FastAPI Implementation: Built on FastAPI for asynchronous request handling, ensuring quick response times even under heavy load conditions.

  • Chunking of Endpoints: Efficiently manages and retrieves endpoint documentation by treating each endpoint as a distinct chunk, making it ideal for large specifications.

MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

TODO

  • The docker image is very large (2GB without pre-downloaded models, 3.76GB with). Help to reduce the size is needed.

Configuration

Customize through environment variables. GLOBAL_TOOL_PROMPT is IMPORTANT!

  • OPENAPI_JSON_DOCS_URL: URL to the OpenAPI specification JSON (default: https://api.staging.readymojo.com/openapi.json)
  • MCP_API_PREFIX: Customizable tool namespace (default: any_openapi).
# Example creating tools with prefix "finance":
docker run -e MCP_API_PREFIX=finance ...
  • GLOBAL_TOOL_PROMPT: Optional text prepended to all tool descriptions. Crucial for accurate tool selection by Claude.
# Example usage:
docker run -e GLOBAL_TOOL_PROMPT="Access to insights APIs for ACME Financial Services abc.com." ...

TL;DR

Motivation: Serve a private API with large Swagger OpenAPI docs (hundreds KB).

  • Claude MCP fails processing large files.
  • Attempts converting to YAML or segmented retrieval failed.
  • Final solution uses in-memory semantic search to find relevant API endpoints by natural language queries (e.g., "list products").
  • Returns complete endpoint docs quickly by chunking one endpoint per chunk.
  • Claude can fully understand what API to call and with all parameters.
  • Separate tool created for making actual REST requests since "fetch" server calls do not work reliably.

Technical flow:

query -> Embedding -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop)
MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

Features

  • Use remote OpenAPI JSON file as source — no local file access or manual updates needed.
  • Semantic search using a lightweight MiniLM-L3 model (43MB vs 90MB).
  • FastAPI-based async server.
  • Endpoint-based chunking of OpenAPI specs (handles 100KB+ docs) preserving endpoint context.
  • Fast in-memory FAISS vector search for instant endpoint discovery.

Limitations

  • No support for linux/arm/v7 (build fails on Transformer library).
  • Cold start penalty (~15s) for model loading if not using the Docker image.
  • Current Docker image disables downloading models; depends on Huggingface. If Huggingface is down, server won't start.
  • Latest Docker image includes pre-downloaded models; revert if issues arise.

Multi-instance Configuration Example

{
  "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 insights apis for ACME Financial Services abc.com .'",
        "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 insights apis for Healthcare API services efg.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}
  • The server auto-extracts base URLs from OpenAPI docs:
    • https://api.finance.com for finance APIs
    • https://api.healthcare.com for healthcare APIs
  • To override base URL, use API_REQUEST_BASE_URL environment variable:
{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e", "API_REQUEST_BASE_URL=https://api.finance.staging.com",
        "-e", "MCP_API_PREFIX=finance",
        "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude Desktop Usage Example

Project prompt:

You should get the api spec details from tools financial_api_request_schema.

Your task is to use financial_make_request tool to make requests to get response. Follow the api spec to add authorization header:
Authorization: Bearer <xxxxxxxxx>

Note: The base URL will be returned in the api_request_schema response, so you don't need to specify it manually.

User example chat input:

Get prices for all stocks

Installation

Installing via Smithery

Automatically install via Smithery CLI:

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

Using pip

pip install mcp-server-any-openapi

Available Tools

The server provides the following tools, where {prefix} is defined by MCP_API_PREFIX.

{prefix}_api_request_schema

Retrieve API endpoint schemas matching your intent. Returns details including path, method, parameters, and response formats.

Input Schema:

{
  "query": {
    "type": "string",
    "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')"
  }
}

{prefix}_make_request

Used for reliable execution of complex APIs where simple implementations fail. Provides:

Input Schema:

{
  "method": {
    "type": "string",
    "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
    "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
  },
  "url": {
    "type": "string",
    "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)"
  },
  "headers": {
    "type": "object",
    "description": "Request headers (optional)",
    "additionalProperties": {
      "type": "string"
    }
  },
  "query_params": {
    "type": "object",
    "description": "Query parameters (optional)",
    "additionalProperties": {
      "type": "string"
    }
  },
  "body": {
    "type": "object",
    "description": "Request body for POST, PUT, PATCH (optional)"
  }
}

Response Format:

{
  "status_code": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    // Response data
  }
}

Docker Support

Multi-Architecture Builds

Official images support linux/amd64 and linux/arm64. Example build commands:

docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

Flexible Tool Naming

Control tool names through MCP_API_PREFIX:

docker run -e MCP_API_PREFIX=finance_ ...

Supported Platforms

  • linux/amd64
  • linux/arm64

Option 1: Use Prebuilt Image (Docker Hub)

docker pull buryhuang/mcp-server-any-openapi:latest

Option 2: Local Development Build

docker build -t mcp-server-any-openapi .

Running the Container

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

Key Components

  1. EndpointSearcher: Core class responsible for:

    • Parsing OpenAPI specifications
    • Creating semantic search index
    • Formatting endpoint documentation
    • Processing natural language queries

  2. Server Implementation:

    • Async FastAPI server
    • MCP protocol support
    • Tool registration and invocation handling

Running from Source

python -m mcp_server_any_openapi

Integration with Claude Desktop

Configure the MCP server in Claude Desktop settings:

{
  "mcpServers": {
    "any_openapi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json",
        "-e", "MCP_API_PREFIX=finance",
        "-e", "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License.

Implementation Notes

  • Endpoint-Centric Processing: Index individual API endpoints using path + method as unique identifiers to maintain context, rather than document-level analysis that can fail on large specs.
  • Optimized Spec Handling: Supports OpenAPI specs up to 10MB (~5,000 endpoints) by employing lazy loading of schema components, parallel path item parsing, and selective embedding generation (excluding redundant descriptions).