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"):
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.
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.
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:
- You can optionally override the base URL using
API_REQUEST_BASE_URLenvironment 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:
- Server Implementation:
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:
- Optimized Spec Handling: Processes OpenAPI specs up to 10MB (~5,000 endpoints) through:
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"):
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.
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.
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:
- You can optionally override the base URL using
API_REQUEST_BASE_URLenvironment 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:
- Server Implementation:
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:
- Optimized Spec Handling: Processes OpenAPI specs up to 10MB (~5,000 endpoints) through: