Skip to main content
Glama
minamorl

@minamorl/openapi-mcp-bridge

by minamorl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@minamorl/openapi-mcp-bridge

Runtime MCP server that dynamically bridges any OpenAPI 3.x spec to MCP tools.

No code generation. No build step. One command.

Quick Start

npx @minamorl/openapi-mcp-bridge --spec https://petstore3.swagger.io/api/v3/openapi.json

Related MCP server: OpenAPI MCP Server

Why not codegen?

Existing tools (openapi-mcp-generator, etc.) generate static TypeScript files from your OpenAPI spec. Every time the API changes, you regenerate, rebuild, redeploy.

openapi-mcp-bridge takes a different approach: runtime bridging. It reads the OpenAPI spec at startup and dynamically creates MCP tools. Update the spec → restart the server. That's it.

Codegen tools

openapi-mcp-bridge

API spec changes

Regenerate → rebuild → restart

Restart only

Setup

npm install → generate → configure → build → start

npx + 1 flag

OAuth2

"Put token in .env"

Built-in auth flows

Transport

stdio only

stdio + Streamable HTTP (planned)

Usage

CLI

# From URL
openapi-mcp-bridge --spec https://api.example.com/openapi.json

# From local file (JSON or YAML)
openapi-mcp-bridge --spec ./api.yaml

# With auth
openapi-mcp-bridge --spec ./api.yaml --auth-type bearer --auth-token $TOKEN

# With custom base URL
openapi-mcp-bridge --spec ./api.yaml --base-url http://localhost:3000

# With custom headers
openapi-mcp-bridge --spec ./api.yaml -H "X-Custom: value"

Claude Desktop / Cursor config

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@minamorl/openapi-mcp-bridge", "--spec", "https://api.example.com/openapi.json"]
    }
  }
}

Programmatic API

import { parseSpec, createBridgeServer, startStdioServer } from "@minamorl/openapi-mcp-bridge";

const doc = await parseSpec("./api.yaml");
const server = await createBridgeServer({ doc, baseUrl: "http://localhost:3000" });
await startStdioServer(server);

How It Works

OpenAPI 3.x spec (JSON/YAML/URL)
        ↓ Parse + resolve $refs
   Tool definitions (name, schema, method, path)
        ↓ Register as MCP tools
   MCP Server (stdio)
        ↓ On tool call
   HTTP request to actual API
        ↓
   Response back to LLM

  1. Parser reads and validates the OpenAPI spec, resolving all $ref references

  2. Mapper converts each operation to an MCP tool with proper input schemas

  3. Server registers tools and handles MCP protocol

  4. Executor translates tool calls into HTTP requests

Auth

# Bearer token
--auth-type bearer --auth-token YOUR_TOKEN

# API key
--auth-type api-key --auth-token YOUR_KEY --api-key-header X-API-Key

# Basic auth (token = base64 of user:pass)
--auth-type basic --auth-token BASE64_CREDENTIALS

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers