MCP Gateway: High-Performance Indexing for OpenAPI Endpoints and Tool Invocation

Development Roadmap

• The current Docker image size is problematic (2GB base, 3.76GB with bundled models). Seeking community assistance to significantly minimize the footprint.

Configuration Parameters

Adjust behavior using environment variables. Setting GLOBAL_TOOL_PROMPT is CRITICAL for prompt engineering alignment.

• OPENAPI_JSON_DOCS_URL: Specifies the remote location of the OpenAPI specification JSON (defaults to https://api.staging.readymojo.com/openapi.json).

• MCP_API_PREFIX: Defines the namespace prefix for the generated tool functions (default is "any_openapi"). Example to create tools like finance_api_request_schema and finance_make_request: bash docker run -e MCP_API_PREFIX=finance ...

• GLOBAL_TOOL_PROMPT: An optional string prepended to every tool's descriptive text. This field strongly influences Claude's decision-making regarding tool selection accuracy. bash # Example: Prepend context for financial APIs docker run -e GLOBAL_TOOL_PROMPT="Secure access to proprietary insights apis for ACME Finance Corp." ...

Executive Summary (Why This Exists)

The Rationale: I needed a robust way to expose a private API, documented via a standard OpenAPI specification file (a few hundred KB in size), to an LLM agent (Claude MCP). - Initial attempts failed due to Claude's context window limitations when processing large raw spec files. - Converting to YAML did not sufficiently reduce size and introduced parsing failures. - Categorizing APIs and attempting group-based doc retrieval also proved inadequate.

The Solution Implemented: - Employs an in-memory vector search engine for rapid, semantic matching of natural language queries (e.g., "retrieve product listing") against endpoint descriptions. - Upon matching, it instantaneously retrieves the entire, context-rich documentation for the precise endpoint(s), stored as discrete chunks, facilitating millisecond response times.

Result: Claude gains precise knowledge of the necessary API call, including all required parameters, structure, and context.

Note: A companion tool within this server package is necessary to perform the actual HTTP request execution, as the generic 'fetch' capability provided elsewhere proved unreliable for this architecture.

Visual representation of data flow/tool usage is available here

Technical Flow Highlights: python User Query -> Vector Embedding -> FAISS Similarity Search (TopK) -> Full OpenAPI Endpoint Details -> MCP Agent (Claude) -> Request Construction -> HTTP Execution -> Result

Key Capabilities

• 🧠 Dynamic Sourcing: Fetches OpenAPI manifest from a remote URL; requires no local file system synchronization for API updates.
• 🔍 Efficient Indexing: Leverages a streamlined MiniLM-L3 embedding model (43MB footprint).
• 🚀 Performance: Built on an asynchronous FastAPI backend.
• 🧠 Granular Context: Chunks specifications at the endpoint level, preserving full context for operations exceeding 100KB document sizes.
• ⚡ Low Latency: Utilizes in-memory FAISS for near-instantaneous discovery of relevant endpoints.

Constraints and Known Issues

• ❌ Incompatibility with older Linux ARM architectures (due to specific Transformer library dependencies).
• 🐢 Startup Delay: Significant cold start penalty (~15 seconds) if the model weights are not pre-loaded (i.e., running without the specialized Docker image).
• [Resolved/Historical Note] Previous versions relied on external HuggingFace model downloads, creating a dependency risk. Current Docker images embed the required models.

Flexible Multi-Instance Deployment Example

This configuration demonstrates setting up separate service instances for distinct API groups, enabling clear logical separation:

{ "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='Authorized access to financial trading analytics APIs.'", "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='Interface for secure patient data retrieval services.'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

In this setup: - The server automatically infers base URLs (e.g., https://api.finance.com). - Base URLs can be forcibly set using API_REQUEST_BASE_URL if required (e.g., pointing to a staging environment):

{ "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='...financial services context...'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

Example Interaction Guidance (Claude Desktop Prompt)

System Context for Claude:

You must utilize the schema definition provided by the tool named 'finance_api_request_schema'. Your objective is to execute necessary actions using the 'finance_make_request' tool. Ensure all requests adhere to the required authorization standard: Authorization: Bearer .

Crucially, the base URL for the API endpoints will be dynamically provided within the schema output of the first tool call; manual specification is unnecessary.

User Chat Example:

Can you retrieve the current pricing data across all active financial instruments?

Installation Methods

Via Smithery (Automated Setup)

For seamless integration with Claude Desktop using Smithery:

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

Using Python Package Manager

bash pip install mcp-server-any-openapi

Exposed Tool Definitions

The service exposes a pair of tools, prefixed by the value of MCP_API_PREFIX.

{prefix}_api_request_schema

Retrieves detailed metadata for API endpoints matching the user's functional intent.

Input Schema:

{ "query": { "type": "string", "description": "A natural language description of the desired API action (e.g., 'Fetch the list of available users' or 'Initiate the account creation workflow')" } }

{prefix}_make_request

Essential for transactional integrity. Facilitates direct, precise HTTP interactions, resolving complexities common in constrained LLM tool execution environments.

Input Schema:

{ "method": { "type": "string", "description": "The designated HTTP verb (GET, POST, PUT, DELETE, PATCH)", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "url": { "type": "string", "description": "The complete, resolved Uniform Resource Locator for the endpoint (e.g., https://api.domain.com/v1/resource/id)" }, "headers": { "type": "object", "description": "Optional map of request headers (e.g., for authorization or content negotiation)", "additionalProperties": { "type": "string" } }, "query_params": { "type": "object", "description": "Optional key-value pairs to be appended to the URL as query string parameters.", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "description": "Optional payload data required for methods that modify state (POST, PUT, PATCH)." } }

Service Response Format:

{ "status_code": 200, "headers": { "content-type": "application/json", "x-request-id": "abc-123" }, "body": { / Parsed response data / } }

Docker Deployment Strategies

Multi-Arch Image Building

Official images support major architectures using buildx: bash docker buildx create --use docker buildx build --platform linux/amd64,linux/arm64 \ -t buryhuang/mcp-server-any-openapi:latest \ --push .

Customizing Tool Prefix via Containerization

Dynamically assign tool names upon container launch: bash

Generates tools prefixed with 'reporting_'

docker run -e MCP_API_PREFIX=reporting_ ...

Supported Architectures

• amd64 (x86_64)
• arm64 (aarch64)

Option 1: Pulling from Docker Hub

bash docker pull buryhuang/mcp-server-any-openapi:latest

Option 2: Local Development Build

bash docker build -t mcp-gateway-local .

Standard Container Execution

bash docker run -d \ -e OPENAPI_JSON_DOCS_URL=https://api.internal.corp/spec.json \ -e MCP_API_PREFIX=prod_ops \ buryhuang/mcp-server-any-openapi:latest

Core System Components

1. EndpointSearcher Engine: The central module responsible for:
2. Ingesting and parsing the OpenAPI schema.
3. Building the high-speed semantic index.
4. Vectorizing natural language inputs.

5. Packaging retrieved documentation for LLM consumption.

6. Gateway Server: The operational framework:

7. Implements the asynchronous server structure using FastAPI.
8. Manages compliance with the MCP tool protocol.
9. Registers and routes tool execution calls.

Execution from Source Code

bash python -m mcp_server_any_openapi

Claude Desktop Configuration Template

Configure this service endpoint within your Claude Desktop client settings:

{ "mcpServers": { "api_discovery_instance": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json", "-e", "MCP_API_PREFIX=service_a", "-e", "GLOBAL_TOOL_PROMPT='Context for service A endpoints.'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

Collaboration Guidelines

1. Clone the repository.
2. Create a dedicated feature branch (e.g., git checkout -b feature/performance-boost).
3. Commit work (git commit -m 'Refactor: Improved embedding batching').
4. Push the branch (git push origin feature/performance-boost).
5. Submit a Pull Request.

Licensing

See the LICENSE file for usage terms.

Advanced Implementation Details

• Granular Indexing Strategy: Moving away from monolithic document indexing, this tool focuses on embedding individual operational units (Path + Method). This allows for focused vector search, specifically targeting parameters and associated context, bypassing context window issues with very large specifications.
• Optimization for Scale: Designed to efficiently process specifications potentially containing thousands of distinct endpoints (~10MB raw text) via:
  • Non-blocking loading of external schema definitions.
  • Concurrent processing during the initial path item parsing phase.
  • Strategic omission of redundant metadata during embedding generation.