openapi-to-mcp

Generate a ready-to-run MCP (Model Context Protocol) server from any OpenAPI/Swagger spec — paste a spec URL, get a working server back, ready to plug into Claude Desktop, Cursor, Windsurf, or deploy over HTTP.

Built on top of agentic-openapi-parser (spec parsing + tool execution) and its McpToolAdapter — this package adds the transport layer (stdio/HTTP), a project scaffolder, and an optional mcp_auth-backed credential provider on top.

Published on npm as agentic-openapi-mcp — the name openapi-to-mcp was already taken by an unrelated package. Every command/import below uses the real published name.

Install

npm install -g agentic-openapi-mcp
# or run without installing:
npx agentic-openapi-mcp <command>

CLI

inspect — preview the tools a spec would produce

Delegates to agentic-openapi-parser inspect (no need to install it separately).

npx agentic-openapi-mcp inspect https://petstore3.swagger.io/api/v3/openapi.json

serve — parse a spec and run it as an MCP server immediately

No files written — useful for local testing or wiring straight into an editor's MCP client config.

npx agentic-openapi-mcp serve https://petstore3.swagger.io/api/v3/openapi.json \
  --transport stdio \
  --auth-type bearer --token "$API_TOKEN" \
  --tag pet

| Flag | Description | Default | |---|---|---| | --transport <mode> | stdio or http | stdio | | --port <port> | Port to listen on (--transport http only) | 3000 | | --auth-type <type> | none, bearer, api-key, or basic | none | | --token <token> | Static credential, required unless --auth-type none | — | | --tag <tag> | Only include tools with this OpenAPI tag (repeatable) | — | | --exclude-tag <tag> | Exclude tools with this OpenAPI tag (repeatable) | — |

generate — scaffold a standalone MCP server project

The deliverable: a self-contained project with its own package.json, src/server.ts, .env.example, and README.md.

npx agentic-openapi-mcp generate https://petstore3.swagger.io/api/v3/openapi.json \
  --out ./petstore-mcp-server \
  --transport http \
  --auth-type bearer

Add --with-mcp-auth instead of a static --auth-type token to have the generated server resolve credentials from a running mcp_auth instance per-owner, instead of a single static token in .env.

Library API

import { generateMcpServer } from 'agentic-openapi-mcp';
import { serveStdio, createHttpServer } from 'agentic-openapi-mcp/transports';

const generated = await generateMcpServer('https://api.example.com/openapi.json', {
  auth: { authType: 'bearer', token: process.env.API_TOKEN },
  filter: { includeTags: ['public'] },
});

// stdio (Claude Desktop, Cursor, Windsurf, mcp-inspector)
await serveStdio(generated);

// or Streamable HTTP
await createHttpServer(generated, { port: 3000 }).start();

generated.createServer() builds a fresh McpServer per call — required for --transport http, where every session needs its own instance (the SDK only allows one transport per server).

mcp_auth-backed credentials

import { generateMcpServer, McpAuthAccessTokenProvider } from 'agentic-openapi-mcp';

const accessTokenProvider = new McpAuthAccessTokenProvider({
  baseUrl: process.env.MCP_AUTH_BASE_URL!,
  clientId: process.env.MCP_AUTH_CLIENT_ID!,
  clientSecret: process.env.MCP_AUTH_CLIENT_SECRET!,
  ownerId: process.env.MCP_AUTH_OWNER_ID!,
  provider: 'github',
  extractToken: (config) => String(config.accessToken),
});

const generated = await generateMcpServer(specUrl, { accessTokenProvider });

Scope (v1)

• No hosted multi-tenant service — each generate run produces a standalone project you deploy yourself. (A multi-tenant gateway is a natural phase 2, following the pattern in mcp_server's streamable_http_standard.)
• No OAuth2 authorization-code flow — bring your own already-valid token (static or via accessTokenProvider), same boundary as agentic-openapi-parser.
• No automatic MCP registry/Smithery listing — generate only writes local files.

Development

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build