🎯 Example MCP Server

API2AI: OpenAPI to MCP-Use Server

Generate production-ready MCP servers from any OpenAPI specification using the highly-used and convenient mcp-use framework (8k+ GitHub stars).

OpenAPI specs are easy to write and organize your code and have 100s of tools available such as the OpenAPI Builder web UI.

Features

🚀 Modern Framework - Uses mcp-use for clean, maintainable code
🔍 Built-in Inspector - Test tools immediately at /inspector
📡 Multiple Transports - HTTP, SSE, and Streamable HTTP support
🎨 UI Widgets - Compatible with ChatGPT Apps SDK and MCP-UI
🔐 Auth Support - Bearer tokens, API keys, custom headers
✨ Zod Schemas - Type-safe parameter validation
🛡️ Security Hardening - Risk classification, policy enforcement, HTTP guardrails
🐳 Production Ready - Docker, PM2, and Kubernetes ready

Quick Start

# Generate a server from the Petstore API
npx api2ai \
  https://petstore3.swagger.io/api/v3/openapi.json \
  ./petstore-mcp \
  --name petstore-api

# Install and run
cd petstore-mcp
npm install
npm start

Open http://localhost:3000/inspector to test your tools!

Usage

CLI

node generate-mcp-use-server.js <openapi-spec> [output-folder] [options]

Options:
  --name <name>            Server name (default: api-mcp-server)
  --base-url <url>         Override API base URL
  --port <port>            Server port (default: 3000)
  --allow-mutations        Enable POST/PUT/PATCH/DELETE tools by default
  --include-tags <tags>    Only include tools with these tags (comma-separated)
  --exclude-tags <tags>    Exclude tools with these tags (comma-separated)
  --approve-writes         Disable approval requirement for restricted tools
  --help                   Show help

Examples

# From remote URL
node generate-mcp-use-server.js \
  https://api.example.com/openapi.json \
  ./my-server \
  --name my-api

# From local file
node generate-mcp-use-server.js \
  ./specs/my-api.yaml \
  ./my-mcp-server \
  --port 8080

# With custom base URL
node generate-mcp-use-server.js \
  ./petstore.json \
  ./petstore \
  --base-url https://petstore.example.com/v3

# Include only read-only tools tagged "public"
node generate-mcp-use-server.js \
  ./api.json \
  ./readonly-server \
  --include-tags public \
  --exclude-tags admin,internal

# Enable writes (mutations) explicitly
node generate-mcp-use-server.js \
  ./api.json \
  ./full-server \
  --allow-mutations \
  --approve-writes

Programmatic Usage

import {
  generateMcpServer,
  extractTools,
  loadOpenApiSpec,
} from "./generate-mcp-use-server.js";

// Generate complete server
const result = await generateMcpServer(
  "https://api.example.com/openapi.json",
  "./output-folder",
  {
    serverName: "my-api",
    baseUrl: "https://api.example.com/v1",
    port: 3000,
    allowMutations: false, // block POST/PUT/PATCH/DELETE by default
    includeTags: ["public"], // only include tools tagged "public"
    excludeTags: ["admin"], // exclude tools tagged "admin"
  },
);

console.log(`Generated ${result.toolCount} tools`);

// Or just extract tools for custom processing
const spec = await loadOpenApiSpec("./my-spec.json");
const tools = extractTools(spec, {
  filterFn: (tool) => tool.riskLevel === "low", // only safe read-only tools
  excludeOperationIds: ["deleteUser"],
});

Security

The generator enforces a three-layer security model in every generated server.

Layer 1 — Generation-time risk classification

Every tool is classified during generation and the result is baked into src/tools-config.js:

Risk level	When assigned	Default behavior
`low`	`GET`, `HEAD`, `OPTIONS` with no dangerous keywords	Enabled, no approval required
`medium`	Any mutating method (`POST`, `PUT`, `PATCH`, `DELETE`)	Blocked unless `ALLOW_RESTRICTED_TOOLS=true`
`high`	Any operation matching admin, auth, billing, payments, tokens, secrets, user management patterns	Blocked, approval required

Use --allow-mutations at generation time to promote medium-risk tools to enabled-by-default, or override at runtime with env vars.

Layer 2 — Runtime policy enforcement

checkToolPolicy() runs before every outbound API call, reading env vars at call-time so you can change policy without regenerating:

ALLOW_RESTRICTED_TOOLS=true    # unlock medium/high-risk tools
REQUIRE_APPROVALS=false        # bypass per-call approval gate

Layer 3 — HTTP hardening

The generated HTTP client enforces these on every request:

Timeouts — configurable via REQUEST_TIMEOUT_MS (default 30 s)
Response size cap — configurable via MAX_RESPONSE_BYTES (default 10 MB)
No redirects — redirect: 'error' prevents host-pivot attacks
Credential header protection — tool arguments cannot override Authorization, Cookie, X-API-Key, or other credential headers; env-configured auth always wins
Host allowlist — ALLOWED_API_HOSTS restricts outbound calls to specific hostnames

Inspector note: The built-in inspector at /inspector exposes all registered tools. In production, restrict access using a reverse proxy or firewall rule.

Generated Output

my-mcp-server/
├── .env              # Environment config (gitignored)
├── .env.example      # Example environment file
├── .gitignore
├── package.json
├── README.md         # Generated documentation
└── src/
    ├── index.js        # Main server with tool registrations
    ├── http-client.js  # Hardened HTTP client
    ├── tools-config.js # Tool configurations with risk metadata
    └── policy.js       # Runtime security policy

Generated Server Features

Built-in Endpoints

Endpoint	Description
`GET /inspector`	Interactive tool testing UI
`POST /mcp`	MCP protocol endpoint
`GET /sse`	Server-Sent Events endpoint
`GET /health`	Health check

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3000`
`NODE_ENV`	`development` / `production`	`development`
`API_BASE_URL`	Base URL for API calls	From spec
`API_KEY`	Bearer token auth	—
`API_AUTH_HEADER`	Custom header (`Name:value`)	—
`MCP_URL`	Public URL for widgets	—
`ALLOWED_ORIGINS`	CORS origins (production)	—
`ALLOW_RESTRICTED_TOOLS`	Allow medium/high-risk tools	`false`
`REQUIRE_APPROVALS`	Require approval for restricted tools	`true`
`ALLOWED_API_HOSTS`	Comma-separated allowed API hostnames	(spec's host)
`REQUEST_TIMEOUT_MS`	Outbound request timeout in ms	`30000`
`MAX_RESPONSE_BYTES`	Maximum response body size in bytes	`10485760`

Connect to Claude Desktop

{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Connect to ChatGPT

The generated server supports the OpenAI Apps SDK out of the box.

Advanced Options

Filter by risk level

const result = await generateMcpServer(specUrl, outputDir, {
  filterFn: (tool) => tool.riskLevel === "low",
});

Filter Tools by Method

const result = await generateMcpServer(specUrl, outputDir, {
  filterFn: (tool) => ["get", "post"].includes(tool.method),
});

Exclude Dangerous Operations

const result = await generateMcpServer(specUrl, outputDir, {
  excludeOperationIds: ["deleteUser", "deleteAllData", "adminReset"],
});

Filter by Path Pattern

const result = await generateMcpServer(specUrl, outputDir, {
  filterFn: (tool) => tool.pathTemplate.startsWith("/api/v2/"),
});

Combine Filters

const result = await generateMcpServer(specUrl, outputDir, {
  excludeOperationIds: ["deleteUser"],
  allowMutations: false,
  filterFn: (tool) =>
    tool.riskLevel === "low" && tool.pathTemplate.includes("/public/"),
});

Comparison with Raw MCP SDK

Feature	This Generator	Raw SDK
Code needed	~50 lines	~200+ lines
Inspector	✅ Built-in	❌ Manual
UI Widgets	✅ Supported	❌ Manual
Zod validation	✅ Generated	❌ Manual
Authentication	✅ Configured	❌ Manual
Risk classification	✅ Automatic	❌ Manual
Runtime policy	✅ Generated	❌ Manual
HTTP hardening	✅ Built-in	❌ Manual
Production ready	✅ Yes	⚠️ Requires work

API2AI - OpenAPI to MCP Server