openapi-to

The OpenAPI to MCP Converter exposes REST API operations defined in an OpenAPI specification as MCP tools. By wrapping an OpenAPI document, it dynamically generates a set of MCP tools that mirror the API endpoints, including support for path parameters, query parameters, request bodies, headers, and various authentication schemes. This enables LLM-based clients (such as the MCP Inspector) to discover and call API operations through the MCP protocol, with the ability to supply authentication and custom headers as part of each operation invocation.

To use it, start the MCP-enabled Java server with your OpenAPI spec and the API base URL. Then connect an MCP client (like MCP Inspector or Claude Desktop) using the provided configuration. The inspector will surface the API operations as tools you can invoke. When calling an operation, you can specify parameters and authentication (bearer tokens, basic auth, or API keys) via the expected MCP headers or configuration fields, and the server will translate those into REST requests to the underlying API.

Prerequisites:

• Java 11 or later
• Maven 3.6 or later (for building from source)
• An OpenAPI specification file in JSON format
• An MCP client (e.g., MCP Inspector or Claude Desktop) for testing

Installation steps:

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

2. Build the project with Maven (produces a fat JAR): mvn clean package This will create a JAR similar to: target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar

3. Prepare your OpenAPI spec and base URL:

   • Place your OpenAPI JSON file at a known path, e.g. /path/to/openapi.json
   • Decide the API base URL, e.g. https://api.example.com

4. Run the server: java -jar target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar /path/to/openapi.json https://api.example.com

5. Connect an MCP client:

   • Use the MCP client to connect via stdio (or as configured by the client).
   • Example configuration for MCP Inspector/Claude requires the command and arguments to launch the Java JAR with the paths above.

Prerequisites note: Ensure Java is properly installed and JAVA_HOME is set. If you modify the OpenAPI spec, rebuild the JAR to reflect changes.

Tips and considerations:

• The converter supports common authentication methods (Bearer, Basic, API keys) and allows per-operation headers. Pass these via the MCP client configuration or operation invocation payload as documented by your MCP client.
• When using relative paths, prefer absolute paths for both the JAR and the OpenAPI spec to avoid runtime path issues in clients like Claude Desktop.
• If an endpoint requires complex request bodies, ensure your OpenAPI spec accurately describes the schema so the generated MCP tools can prompt for the correct payload.
• Keep the OpenAPI spec up to date; after changes, rebuild the fat JAR to reflect new/modified operations.
• Logging can help diagnose issues; check the console output of the Java process for hints about missing parameters or authentication failures.