openapi2mcp

⚠️ 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:

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.

Related MCP server: OpenAPI MCP Server

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.

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

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

Contributing

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

Roadmap

• 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