The MCP OpenAPI Proxy automates the creation of MCP-compatible server tooling from an OpenAPI specification. It reads the OpenAPI document, generates the necessary MCP server components, and exposes endpoints that conform to the MCP protocol. This allows you to rapidly provision MCP endpoints that mirror the semantics described in your OpenAPI spec, enabling streamlined integration with MCP clients and tooling. You can run the proxy as a standalone service in a container or directly on a host, and it supports configuring the bind host/port and transport type to suit your deployment.

Once running, you can use the included validation tooling to list available MCP tools and execute them. The repository provides a Python-based client example that can query http://localhost:8000/mcp to enumerate tools and then call a specific tool with the appropriate arguments. This makes it straightforward to verify that the generated MCP server behaves according to the OpenAPI specification and to test tool execution in your environment.

Prerequisites:

• Python 3.8+ (recommended)
• Access to install Python packages (pip)
• Optional: Docker for containerized deployment

Installation steps:

1. Clone the repository: git clone https://github.com/electrocucaracha/mcp-openapi-proxy.git cd mcp-openapi-proxy

2. Create and activate a Python virtual environment (recommended): python3 -m venv venv source venv/bin/activate # on Unix or macOS venv\Scripts\activate # on Windows

3. Install dependencies (if a requirements file is provided): pip install -r requirements.txt

   If no requirements file exists, install as needed per project docs

4. Configure environment variables (OPENAPI_SPEC_URL, HOST, PORT, TRANSPORT) as needed for your environment. You can also export them in a shell script or set them in a service manager.

5. Run the proxy: python -m mcp_openapi_proxy

6. Verify the service is up by querying the MCP endpoint: curl http://127.0.0.1:8000/mcp

Optional: If you prefer containerized deployment, build or pull a suitable Docker image and run with appropriate environment variables and port mappings.

Environment variable guidance:

• OPENAPI_SPEC_URL: Provide the URL to your OpenAPI specification that defines the MCP surface.
• TRANSPORT: Choose the transport mechanism (default streamable-http) used for MCP communication.
• HOST/PORT: Bind address and port for the MCP server endpoint.

Common issues:

• If OPENAPI_SPEC_URL is unreachable, verify network access and URL correctness.
• Ensure the OpenAPI spec aligns with MCP-compatible operations to avoid generation errors.
• When running in containers, map port 8000 (or your configured port) to the host and ensure network policies allow access.
• If using a virtual environment, activate it before starting the server to ensure dependencies are resolved.

Configuration tips:

• You can override defaults at runtime by exporting environment variables or supplying a startup script.
• If you need to run multiple MCP endpoints, define multiple entries under mcpServers with distinct names and ports.