API2MCP — turn any OpenAPI spec into a paid MCP server

OKX.AI Genesis Hackathon · Software Utility track

API2MCP is an Agentic Service Provider (ASP): give it any OpenAPI 3.x spec (JSON or YAML) and it generates a complete, ready-to-deploy TypeScript MCP server scaffold — one MCP tool per API operation, proxying the upstream API — with x402 pay-per-call billing already wired in.

It is deliberately meta: API2MCP is itself an MCP service that other agents pay (via x402) to call, and each call mints another monetizable ASP for the OKX.AI marketplace. One paid service that manufactures more paid services. See the ASP tutorial: https://www.okx.ai/tutorial/asp.

Generation is fully deterministic — plain template strings, no LLM calls.

How it works

OpenAPI 3.x spec (JSON/YAML)
        |
        v
  API2MCP generator  ──────────────►  generated project (file map / zip)
   - parse + light validation           package.json, tsconfig.json
   - 1 operation -> 1 MCP tool          src/server.ts   (Express + MCP Streamable HTTP,
   - params/body -> Zod schemas                          fetch-proxy to the upstream API)
   - servers[0]  -> upstream base URL   src/x402.ts     (env-driven pay-per-call gate)
                                        README.md, .env.example, .gitignore

Run it

npm install
npm run dev        # starts http://localhost:4402  (tsx watch)
# or: npm run build && npm start
npm test           # acceptance test: generated project must npm install + tsc cleanly

Interfaces

MCP (Streamable HTTP, stateless) — POST /mcp

Tool	Pricing	Description
generate_mcp_server	paid	{openapi_spec, service_name?, price_usd?} → {files: {path: content}, tool_count, instructions}
preview_tools	free	{openapi_spec} → list of {name, description, params} it would generate (teaser)

curl -s http://localhost:4402/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

REST

Endpoint	Pricing	Returns
POST /api/generate	paid	JSON {service_name, tool_count, tools, files, instructions}
POST /api/generate.zip	paid	zip archive of the generated project
POST /api/preview	free	tool listing teaser

# Generate an MCP server from the bundled petstore fixture:
node -e 'console.log(JSON.stringify({openapi_spec: require("fs").readFileSync("examples/petstore.json","utf8"), price_usd: 0.01}))' \
  | curl -s http://localhost:4402/api/generate -H 'Content-Type: application/json' -d @- \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s);console.log(r.service_name, r.tool_count, Object.keys(r.files));})'

# Or download it as a zip:
node -e 'console.log(JSON.stringify({openapi_spec: require("fs").readFileSync("examples/petstore.json","utf8")}))' \
  | curl -s http://localhost:4402/api/generate.zip -H 'Content-Type: application/json' -d @- -o petstore-mcp.zip

CLI (local use, no server)

npx tsx src/cli.ts examples/petstore.json -o out/
cd out/petstore-mcp && npm install && npm run dev

OKX payment

Paid calls are settled via OKX's official x402 seller middleware (@okxweb3/x402-express + @okxweb3/x402-core + @okxweb3/x402-evm) against the OKX facilitator on X Layer (eip155:196).

Route	Price
POST /api/generate	$0.50
POST /api/generate.zip	$0.50
POST /api/preview	$0.01

Env vars (all four OKX values plus PAYMENT_ENABLED=true are required to activate payments; create keys at https://web3.okx.com/onchainos/dev-portal):

PAYMENT_ENABLED=true
OKX_API_KEY=...
OKX_SECRET_KEY=...
OKX_PASSPHRASE=...
PAY_TO_ADDRESS=0xYourWalletAddress

With payment active, unpaid requests to the paid routes get HTTP 402 with an x402Version: 2 payment-required body listing the accepted exact-scheme X Layer payment option. If any variable is missing, or OKX initialization fails, the server logs one line and serves everything free — deploys stay safe until real keys exist. /healthz, / and /mcp are never payment-gated.

Generated projects ship the same env-driven stub (PAYMENT_ENABLED, PAY_TO_ADDRESS, PRICE_USD, X402_NETWORK) so every scaffold is monetizable out of the box.

Acceptance test

npm test is the quality bar: it generates a project from examples/petstore.json (5 operations: path params, query params, header param, enum, $ref/allOf schemas, POST/PUT bodies), writes it to a temp dir, runs npm install and npm run build (tsc) inside it, and fails unless the generated code compiles. Set KEEP_GENERATED=1 to keep the temp project around.

Layout

src/generator/   deterministic OpenAPI -> MCP project generator
  parse.ts         JSON/YAML parsing + light structural validation
  operations.ts    operation -> tool extraction (names, params, bodies)
  zod-codegen.ts   JSON Schema -> Zod source translation ($ref, enum, allOf/oneOf/anyOf)
  templates.ts     file templates for the generated project
src/server.ts    API2MCP service (MCP endpoint + REST + zip)
src/x402.ts      OKX x402 payment middleware (@okxweb3/x402-express, env-gated no-op by default)
src/cli.ts       local generation CLI
examples/        petstore fixture
test/validate.ts acceptance test (generated project must compile)