MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

TODO

• The docker image is 2GB without pre-downloaded models. Its 3.76GB with pre-downloaded models!! Too big, someone please help me to reduce the size.

Configuration

• OPENAPI_JSON_DOCS_URL

  : URL to the OpenAPI specification JSON (defaults to https://api.staging.readymojo.com/openapi.json)

• MCP_API_PREFIX

  : Customizable tool namespace (default "any_openapi"):

  # Creates tools: custom_api_request_schema and custom_make_request
  docker run -e MCP_API_PREFIX=finance ...
  

• GLOBAL_TOOL_PROMPT

  : Optional text to prepend to all tool descriptions. This is crucial to make the Claude select and not select your tool accurately.

  # Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions
  docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ...
  

TL'DR

• Claude MCP simply error on processing these size of file
• I attempted convert the result to YAML, not small enough and a lot of errors. FAILED
• I attempted to provide a API category, then ask MCP Client (Claude Desktop) to get the api doc by group. Still too big, FAILED.

• It uses in-memory semantic search to find relevant Api endpoints by natural language (such as list products)
• It returns the complete end-point docs (as I designed it to store one endpoint as one chunk) in millionseconds (as it's in memory)

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 system access, no updating required for API changes
• 🔍 Semantic search using optimized MiniLM-L3 model (43MB vs original 90MB)
• 🚀 FastAPI-based server with async support
• 🧠 Endpoint based chunking OpenAPI specs (handles 100KB+ documents), no loss of endpoint context
• ⚡ In-memory FAISS vector search for instant endpoint discovery

Limitations

• Not supporting linux/arm/v7 (build fails on Transformer library)
• 🐢 Cold start penalty (~15s for model loading) if not using docker image
• [Obsolete] Current docker image disabled downloading models. You have a dependency over huggingface. When you load the Claude Desktop, it takes some time to download the model. If huggingface is down, your server will not start.
• The latest docker image is embedding pre-downloaded models. If there is issues, I would revert to the old one.

Multi-instance config 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 will automatically extract base URLs from the OpenAPI docs:

  • https://api.finance.com

    for finance APIs

  • https://api.healthcare.com

    for healthcare APIs
• You can optionally override the base URL using

  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

You should get the api spec details from tools financial_api_request_schema

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

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

Get prices for all stocks

Installation

Installing via Smithery

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

Using pip

pip install mcp-server-any-openapi

Available Tools

{prefix}

MCP_API_PREFIX

{prefix}_api_request_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

{
    "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)"
    }
}

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

Docker Support

Multi-Architecture Builds

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

Flexible Tool Naming

MCP_API_PREFIX

# Produces tools with "finance_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 that handles:
   • OpenAPI specification parsing
   • Semantic search index creation
   • Endpoint documentation formatting
   • Natural language query processing
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

{
  "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

Implementation Notes

• Endpoint-Centric Processing: Unlike document-level analysis that struggles with large specs, we index individual endpoints with:
  • Path + Method as unique identifiers
  • Parameter-aware embeddings
  • Response schema context
• Optimized Spec Handling: Processes OpenAPI specs up to 10MB (~5,000 endpoints) through:
  • Lazy loading of schema components
  • Parallel parsing of path items
  • Selective embedding generation (omits redundant descriptions)