MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

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:

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:

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:

Claude Desktop Usage Example

Claude Desktop Project Prompt:

In chat, you can do:

Installation

Installing via Smithery

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

Using pip

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:

{prefix}_make_request

Essential for reliable execution with complex APIs where simplified implementations fail. Provides:

Input Schema:

Response Format:

Docker Support

Multi-Architecture Builds

Official images support 3 platforms:

Flexible Tool Naming

Control tool names through MCP_API_PREFIX:

Supported Platforms

• linux/amd64
• linux/arm64

Option 1: Use Prebuilt Image (Docker Hub)

Option 2: Local Development Build

Running the Container

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

Integration with Claude Desktop

Configure the MCP server in your Claude Desktop settings:

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)