agent-openapi-mcp

Live OpenAPI runtime proxy — call any REST API from Claude, Cursor, or any MCP client without writing wrapper code.

The Problem

Every time you want Claude to interact with a REST API, you have to:

1. Write a custom MCP server (2-3 hours of boilerplate)
2. Deploy it
3. Maintain it forever

Static generators like MCPForge require code gen + deploy — one-time, not live.

This server is the missing runtime layer. Point it at any OpenAPI spec URL — it handles everything at request time.

---

Quick Start

Add to your MCP config (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "openapi": {
      "url": "https://agent-openapi-mcp.onrender.com/mcp"
    }
  }
}

That's it. Now ask Claude:

"Load the Petstore API spec from https://petstore3.swagger.io/api/v3/openapi.json and list all the pet operations"

---

MCP Tools

openapi_load_spec

Load and cache an OpenAPI spec by URL. Returns a summary.

spec_url: "https://petstore3.swagger.io/api/v3/openapi.json"
cache_ttl: 300  # seconds (default 300, max 3600)

Returns: { spec_id, title, version, base_url, operation_count, tags, servers }

---

openapi_list_operations

List all operations in a spec (auto-loads if not cached).

spec_url: "https://petstore3.swagger.io/api/v3/openapi.json"
tag: "pet"        # optional filter
method: "GET"     # optional filter

Returns array of { operation_id, method, path, summary, tags, parameters, request_body }

---

openapi_call_endpoint

Execute a specific API endpoint. This is the core tool.

spec_url: "https://petstore3.swagger.io/api/v3/openapi.json"
operation_id: "getPetById"
path_params: '{"petId": "1"}'
query_params: '{"limit": "10"}'
body: '{"name": "doggie"}'
headers: '{"Authorization": "Bearer token123"}'
timeout: 30

Returns: { status_code, headers, body, elapsed_ms, url, method }

---

openapi_search_operations

Keyword search across operation summaries and descriptions.

spec_url: "https://petstore3.swagger.io/api/v3/openapi.json"
query: "find pets by status"

Returns ranked list of matching operations.

---

Example Conversation

You: Load https://petstore3.swagger.io/api/v3/openapi.json and find all operations 
     related to "inventory"

Claude: [calls openapi_load_spec, then openapi_search_operations]
        Found 1 operation: getInventory — GET /store/inventory
        "Returns pet inventories by status"

You: Call it

Claude: [calls openapi_call_endpoint with operation_id="getInventory"]
        Status 200 — {"available": 847, "sold": 42, "pending": 3}

---

REST API

The server also exposes a REST API at /api/v1/*:

Endpoint	Method	Description
/api/v1/load-spec	POST	Load and cache a spec
/api/v1/list-operations	POST	List operations
/api/v1/call-endpoint	POST	Execute an endpoint
/api/v1/search-operations	POST	Search operations
/health	GET	Health check
/docs	GET	Swagger UI

Example REST call

curl -X POST https://agent-openapi-mcp.onrender.com/api/v1/load-spec \
  -H "Content-Type: application/json" \
  -d '{"spec_url": "https://petstore3.swagger.io/api/v3/openapi.json"}'

---

Self-Hosting with Docker

docker build -t agent-openapi-mcp .
docker run -p 8080:8080 \
  -e PUBLIC_HOST=localhost:8080 \
  agent-openapi-mcp

Then use http://localhost:8080/mcp as your MCP URL.

Environment Variables

Variable	Default	Description
PUBLIC_HOST	agent-openapi-mcp.onrender.com	Public hostname
PORT	8080	Port to listen on
X402_WALLET_ADDRESS	(none)	Enable x402 micropayment paywall

---

Supported Spec Formats

• OpenAPI 3.x (JSON and YAML)
• Swagger 2.x (JSON and YAML)
• Any publicly accessible URL

---

Rate Limits

• Free tier: 100 requests per IP per day
• Paid: Include X-Payment header (x402 micropayments)

---

Development

git clone https://github.com/aparajithn/agent-openapi-mcp
cd agent-openapi-mcp
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run locally
uvicorn src.main:app --reload --port 8080

---

License

MIT © aparajithn