# agent-openapi-mcp

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

[![glama](https://glama.ai/mcp/servers/badge/aparajithn/agent-openapi-mcp)](https://glama.ai/mcp/servers/aparajithn/agent-openapi-mcp)

## 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.):

```json
{
  "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

```bash
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

```bash
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

```bash
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](https://github.com/aparajithn)