[md]OpenAPI MCP Proxy

The OpenAPI MCP Proxy tool converts any OpenAPI-compliant REST API into an MCP server that AI agents can interact with.

Features

• Automatic tool generation — converts OpenAPI operations into MCP tools with proper JSON schemas
• Multi-agent support — works with Claude Desktop, Cursor, and OpenCode via automatic config generation
• Interactive management — interactive shell for browsing and selecting API operations
• Flexible input — load specs from URLs (https://api.example.com/openapi.json) or local files
• Full HTTP support — handles GET, POST, PUT, DELETE, PATCH with path params, query params, headers, and request bodies

Installation

# Build the executable JAR
sbt openapiMcpProxy/assembly

# The JAR is created as ./openapi-mcp-proxy.jar
# Make it executable and add to your PATH
chmod +x openapi-mcp-proxy.jar
mv openapi-mcp-proxy.jar /usr/local/bin/openapi-mcp-proxy

Commands

Supported agents:

• claude — Claude Code (.mcp.json)
• claude-desktop — Claude Desktop app (macOS only)
• cursor — Cursor IDE (.cursor/mcp.json)
• opencode — OpenCode (opencode.json)

Quick start

1. List available operations

See what endpoints are available in an OpenAPI spec:

openapi-mcp-proxy list https://api.example.com/openapi.json
# or
openapi-mcp-proxy list ./my-api-spec.yaml

Output:

  GET    /users       listUsers
  POST   /users       createUser
  GET    /users/{id}  getUserById
  DELETE /users/{id}  deleteUser

2. Register with your AI agent

Option A: use the built-in config manager (recommended)

# Add specific operations for Claude Desktop
openapi-mcp-proxy mcp add --agent claude-desktop https://api.example.com/openapi.json listUsers getUserById

# Add all operations (with confirmation if >10 endpoints)
openapi-mcp-proxy mcp add --agent claude-desktop https://api.example.com/openapi.json '*'

# Interactive mode — browse and select operations
openapi-mcp-proxy mcp add --agent cursor https://api.example.com/openapi.json

# Manage existing entries
openapi-mcp-proxy mcp manage --agent opencode

Option B: manual configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "openapi-my-api": {
      "command": "openapi-mcp-proxy",
      "args": ["proxy", "https://api.example.com/openapi.json", "listUsers", "getUserById"]
    }
  }
}

OpenCode (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openapi-my-api": {
      "type": "local",
      "command": ["openapi-mcp-proxy", "proxy", "./my-api.yaml", "searchItems", "createOrder"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "my-api": {
      "command": "openapi-mcp-proxy",
      "args": ["proxy", "https://api.example.com/openapi.json", "listUsers"]
    }
  }
}

How it works

1. Spec loading — loads OpenAPI 3.x specs from URL or file (JSON or YAML)
2. Schema conversion — converts OpenAPI schemas to MCP-compatible JSON schemas
3. Tool generation — each selected operation becomes an MCP tool with:
   • Input schema from path/query/header parameters and request body
   • Output schema from 200/201/default response
   • Description from operation summary
4. Request execution — when called, constructs and executes HTTP requests using http4s

Example: EVE Online ESI API

The repository includes an example configuration for the EVE Online ESI API. See .mcp.json:

{
  "mcpServers": {
    "eve-online": {
      "command": "openapi-mcp-proxy",
      "args": ["proxy", "https://esi.evetech.net/latest/swagger.json",
        "get_characters_character_id",
        "get_corporations_corporation_id",
        "post_universe_ids"]
    }
  }
}

Configuration management

The mcp subcommands handle different config file formats automatically:

Server names are auto-derived from the spec title (e.g., "EVE Swagger Interface" → openapi-eve-swagger-interface).

Tips

• Start small — add only the operations you need to avoid bloating the context window
• Use wildcards carefully — adding * includes all operations; you'll be warned if >10 endpoints
• Mix and match — can run multiple openapi-mcp-proxy instances for different APIs
• Security — the proxy executes HTTP requests as-is; ensure your API has proper auth if needed