OpenAPI AnyApi

What is mcp-server-any-openapi?

mcp-server-any-openapi is a Claude Message Control Protocol (MCP) server that allows Claude to semantically search and interact with any API endpoint defined in an OpenAPI specification. It addresses the challenge of integrating large API documentation with Claude Desktop by intelligently chunking OpenAPI specifications and providing built-in request execution capabilities. This makes it ideal for connecting private or extensive APIs to Claude Desktop.

How to use mcp-server-any-openapi?

To use mcp-server-any-openapi, you can either install it via pip, use the pre-built Docker image, or run it from source. The server is configured primarily through environment variables such as OPENAPI_JSON_DOCS_URL (for the OpenAPI spec URL), MCP_API_PREFIX (for customizing tool namespaces), and GLOBAL_TOOL_PROMPT (for guiding Claude's tool selection). Once running, you integrate it with Claude Desktop by configuring the MCP server in your Claude Desktop settings, providing the necessary command and arguments for the Docker container or local execution. Claude can then use the _api_request_schema tool to discover endpoints and the _make_request tool to execute API calls.

Key Features of mcp-server-any-openapi

• Remote OpenAPI Source: Uses remote OpenAPI JSON files, eliminating the need for local file access and manual updates.
• Semantic Search: Employs an optimized MiniLM-L3 model for efficient semantic search of API endpoints.
• FastAPI Server: Built on FastAPI with asynchronous support for high performance.
• Endpoint-based Chunking: Intelligently chunks OpenAPI specifications by endpoint, preserving context and handling large documents (100KB+).
• In-memory FAISS Vector Search: Provides instant endpoint discovery through in-memory FAISS vector search.
• Flexible Tool Naming: Allows customization of tool names via MCP_API_PREFIX.
• Multi-Architecture Docker Support: Official Docker images support linux/amd64 and linux/arm64.

Use Cases of mcp-server-any-openapi

• Integrating Private APIs with Claude Desktop: Seamlessly connect internal or private APIs to Claude for natural language interaction.
• Handling Large OpenAPI Specifications: Overcome limitations of Claude's direct processing of large API docs by providing a semantically searchable interface.
• Automating API Interactions: Enable Claude to discover and execute complex API requests based on natural language queries.
• Multi-instance API Management: Configure multiple instances of the server to manage and interact with different sets of APIs (e.g., finance, healthcare).

FAQ about mcp-server-any-openapi

Q: Why was this project created? A: The project was created to address the challenge of Claude's inability to process large OpenAPI documentation files, which often resulted in errors. The goal was to enable Claude to effectively discover and call API endpoints from extensive specifications.

Q: How does it handle large OpenAPI files? A: It uses in-memory semantic search and endpoint-based chunking. Instead of processing the entire document, it indexes individual endpoints, allowing Claude to find relevant APIs by natural language and receive full endpoint details.

Q: What are the main limitations? A: Current limitations include a cold start penalty (around 15 seconds for model loading if not using Docker), and past issues with Docker image size and reliance on Hugging Face for model downloads (though the latest images embed pre-downloaded models).

Q: Can I customize the tool names? A: Yes, you can customize the tool namespace by setting the MCP_API_PREFIX environment variable when running the Docker container or the server from source.

Q: How does it ensure Claude selects the correct tool? A: The GLOBAL_TOOL_PROMPT environment variable is crucial. It allows you to prepend optional text to all tool descriptions, helping Claude accurately select or deselect the appropriate tool based on the context of the conversation.

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

Customize through environment variables. GLOBAL_TOOL_PROMPT is IMPORTANT!

• 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

Why I create this: I want to serve my private API, whose swagger openapi docs is a few hundreds KB in size.

• 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.

Eventually I came down to this solution:

• 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)

Boom, Claude now knows what API to call, with the full parameters!

Wait I have to create another tool in this server to make the actual restful request, because "fetch" server simply don't work, and I don't want to debug why.

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

Technical highlights:

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

Here is the multi-instance config example. I design it so it can more flexibly used for multiple set of apis:

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

In this example:

• 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

Claude Desktop Project Prompt:

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.

In chat, you can do:

Get prices for all stocks

Installation

Installing via Smithery

To install Scalable OpenAPI Endpoint Discovery and API Request Tool for Claude Desktop automatically via Smithery:

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 determined by MCP_API_PREFIX):

{prefix}_api_request_schema

Get API endpoint schemas that match your intent. Returns endpoint 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

Essential for reliable execution with complex APIs where simplified 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 3 platforms:

# 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

Control tool names through 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

Configure the MCP server in your 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 terms included in the LICENSE file.

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)