Integrations
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"):CopyGLOBAL_TOOL_PROMPT
: Optional text to prepend to all tool descriptions. This is crucial to make the Claude select and not select your tool accurately.Copy
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 APIshttps://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
- EndpointSearcher: Core class that handles:
- OpenAPI specification parsing
- Semantic search index creation
- Endpoint documentation formatting
- Natural language query processing
- 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
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - 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)
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
This server facilitates scalable discovery and execution of OpenAPI endpoints using semantic search and high-performance processing, overcoming limitations of large spec handling for streamlined API interactions.
- TODO
- Configuration
- TL'DR
- Features
- Limitations
- Multi-instance config example
- Claude Desktop Usage Example
- Installation
- Available Tools
- Docker Support
- Integration with Claude Desktop
- Contributing
- License
- Implementation Notes
Related Resources
Related MCP Servers
- -securityAlicense-qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.Last updated -2PythonMIT License
- -securityFlicense-qualityThis server acts as a Message Communication Protocol (MCP) service for integrating Apifox and Cursor, enabling OpenAPI interface implementation through AI-driven interaction.Last updated -7TypeScript
- -securityAlicense-qualityA server that enables Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the Model Context Protocol.Last updated -7278TypeScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that loads multiple OpenAPI specifications and exposes them to LLM-powered IDE integrations, enabling AI to understand and work with your APIs directly in development tools like Cursor.Last updated -72927TypeScriptMIT License