OpenAPI MCP Bridge

Transform OpenAPI definitions into MCP (Model Context Protocol) tools for seamless LLM-API integration.

What is MCP?

Model Context Protocol (MCP) is a standard protocol that allows AI models to interact with external tools and data sources. Unlike REST APIs that use HTTP requests, MCP uses JSON-RPC messages over stdio or WebSocket connections.

Key Differences:

• REST API: HTTP requests → JSON responses
• MCP: JSON-RPC messages → Tool calls and responses
• Purpose: MCP bridges AI models with external systems safely and efficiently

Why OpenAPI → MCP?

• Your APIs are already documented in OpenAPI format
• AI models can't directly call REST APIs
• MCP provides a secure, standardized way to expose API functionality to AI

Quick Start (30 seconds)

1. Install and Run

npm install -g openapi-mcp-bridge
mkdir my-api && cd my-api

2. Create OpenAPI Definition

cat > museum-api.yaml << 'EOF'
openapi: 3.1.0
info:
  title: Museum API
  version: 1.0.0
servers:
  - url: https://redocly.com/_mock/demo/openapi/museum-api
paths:
  /museum-hours:
    get:
      summary: Get museum hours
      operationId: getMuseumHours
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
EOF

3. Test with MCP Inspector

# Terminal 1: Start MCP server
openapi-mcp-bridge --definitions .

# Terminal 2: Test with inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector npx openapi-mcp-bridge --definitions .

Result: You'll see getMuseumHours tool available in the MCP Inspector interface.

Integration Examples

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "museum-api": {
      "command": "npx",
      "args": ["openapi-mcp-bridge", "--definitions", "/path/to/your/api-definitions"]
    }
  }
}

Usage: Ask Claude "What are the museum hours?" and it will automatically call your API.

Claude Code Integration

1. Create .claude-code-mcp.json in your project:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["openapi-mcp-bridge", "--definitions", "./api-definitions"]
    }
  }
}

2. Claude Code will automatically detect and use your API tools.

Custom MCP Client

// TypeScript example with proper ES module setup
import { spawn } from 'child_process';
import { MCPClient } from '@modelcontextprotocol/client';

const serverProcess = spawn('npx', ['openapi-mcp-bridge', '--definitions', './api-definitions']);
const client = new MCPClient();

await client.connect({ 
  stdio: { 
    stdin: serverProcess.stdin, 
    stdout: serverProcess.stdout 
  } 
});

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Call a tool
const result = await client.callTool('getMuseumHours', { date: '2024-01-15' });
console.log('Result:', result);

Usage Patterns

When to Use Each Approach

Use Case	Approach	Best For
AI Model Integration	CLI (openapi-mcp-bridge)	Claude Desktop, Claude Code, custom MCP clients
Web Application	Express/Fastify middleware	Adding MCP endpoints to existing web apps
Microservice	Standalone server	Dedicated MCP service, Docker deployments
Development/Testing	MCP Inspector	Testing and debugging MCP tools

Decision Tree

Do you want to integrate with an AI model?
├── Yes → Use CLI approach
│   ├── Claude Desktop → Update claude_desktop_config.json
│   ├── Claude Code → Use `claude mcp add` command
│   └── Custom client → Use stdio connection
└── No → Use HTTP approach
    ├── Existing Express app → Use Express middleware
    ├── New microservice → Use standalone server
    └── Testing → Use MCP Inspector

Transport Mode Decision Matrix

Transport	Use Case	Pros	Cons	Best For
stdio	AI model integration	Simple, secure, no network config	Single process, local only	Claude Desktop, Claude Code, development
HTTP	Web applications	Multi-user, remote access, familiar	Network setup, security concerns	Production APIs, microservices
WebSocket	Real-time updates	Bi-directional, low latency	Complex setup, connection management	Streaming, live data

stdio is the recommended transport for AI model integration because:

• ✅ Security: No network exposure or authentication needed
• ✅ Simplicity: Direct process communication
• ✅ Performance: Lower overhead than HTTP
• ✅ Reliability: No network connectivity issues
• ✅ Lifecycle: Automatic process management

Troubleshooting

Common Issues

1. Import Path Errors

# ❌ Error: Cannot find module 'openapi-mcp-bridge/express'
import { createExpressMiddleware } from 'openapi-mcp-bridge/express';

# ✅ Solution: Use the correct package exports
import { createExpressMiddleware } from 'openapi-mcp-bridge/express';

Root Cause: Package uses ES modules. Ensure your package.json has "type": "module".

2. "Cannot POST /mcp" Error

# ❌ Wrong: Trying to make HTTP requests to MCP endpoint
curl -X POST http://localhost:3000/mcp

# ✅ Right: Use MCP Inspector or MCP client
mcp-inspector http://localhost:3000/mcp

Root Cause: MCP is not a REST API. It uses JSON-RPC over stdio/WebSocket.

3. Port Conflicts

# ❌ Error: EADDRINUSE: address already in use :::3000
npm start

# ✅ Solution: Use a different port
PORT=3001 npm start
# or
npx openapi-mcp-bridge --definitions . --port 3001

4. CLI Warnings

# ❌ Warning: --port is not yet implemented in stdio mode
openapi-mcp-bridge --definitions . --port 3000

# ✅ Solution: Don't use --port with CLI (stdio mode)
openapi-mcp-bridge --definitions .

Root Cause: CLI runs in stdio mode for MCP clients. Use standalone server for HTTP mode.

5. Module Import Issues

// ❌ CommonJS in ES module project
const { createExpressMiddleware } = require('openapi-mcp-bridge/express');

// ✅ ES modules syntax
import { createExpressMiddleware } from 'openapi-mcp-bridge/express';

Setup for TypeScript projects:

// package.json
{
  "type": "module",
  "scripts": {
    "start": "tsx src/server.ts"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "ES2022",
    "moduleResolution": "node",
    "target": "ES2022",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Debug Mode

Enable detailed logging:

# CLI
openapi-mcp-bridge --definitions . --debug

# Environment variable
DEBUG=true openapi-mcp-bridge --definitions .

# Programmatic
const config = {
  logging: { consoleFallback: true },
  debug: true
};

Validation Issues

# Check if OpenAPI file is valid
npx @redocly/cli lint your-api.yaml

# Force cache regeneration
OPENAPI_FORCE_REGEN=true openapi-mcp-bridge --definitions .

# Test tool generation
mcp-inspector npx openapi-mcp-bridge --definitions .

Advanced Usage

Express Integration

// server.ts
import express from 'express';
import { createExpressMiddleware } from 'openapi-mcp-bridge/express';

const app = express();

// Add MCP endpoint
app.use('/mcp', createExpressMiddleware({
  definitionsDirectory: './api-definitions',
  defaultCredentials: {
    username: process.env.API_USERNAME,
    password: process.env.API_PASSWORD
  }
}));

// Add health check
app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

app.listen(3000, () => {
  console.log('MCP server: http://localhost:3000/mcp');
});

Standalone Server

import { MCPServer } from 'openapi-mcp-bridge';

const server = new MCPServer({
  definitionsDirectory: './api-definitions',
  port: 3000,
  mountPath: '/mcp',
  defaultCredentials: {
    username: process.env.API_USERNAME,
    password: process.env.API_PASSWORD
  }
});

await server.start();
console.log('MCP server running on http://localhost:3000/mcp');

Configuration

interface Config {
  definitionsDirectory: string;
  cacheDirectory?: string;
  defaultCredentials?: {
    username?: string;
    password?: string;
    token?: string;
    apiKey?: string;
  };
  logging?: {
    winston?: any;
    pino?: any;
    consoleFallback?: boolean;
  };
  mcpOptions?: {
    serverName?: string;
    serverVersion?: string;
  };
}

🏷️ Tool Naming & Discoverability

Naming Patterns

The library generates predictable tool names from OpenAPI operations:

OpenAPI Operation	Generated Tool Name	Rule
GET /museum-hours with operationId: getMuseumHours	getMuseumHours	Uses operationId when available
POST /special-events with operationId: createSpecialEvent	createSpecialEvent	Uses operationId when available
GET /events/{eventId}	get-events-by-eventId	Auto-generated: {method}-{path}-by-{param}
DELETE /tickets/{ticketId}	delete-tickets-by-ticketId	Auto-generated: {method}-{path}-by-{param}
PATCH /users/{userId}/profile	patch-users-by-userId-profile	Auto-generated: handles nested paths

Custom Tool Names

Override generated names using customization:

# museum-api.custom.yaml
toolAliases:
  "getMuseumHours": "get-hours"
  "createSpecialEvent": "create-event"
  "get-events-by-eventId": "get-event-details"

Tool Discovery

List available tools programmatically:

# Using MCP Inspector
mcp-inspector npx openapi-mcp-bridge --definitions ./api-definitions

# In Claude Code
"What tools are available?"

# In Claude Desktop
"List all museum API tools"

📁 Project Structure

your-project/
├── api-definitions/
│   ├── museum-api.yaml          # OpenAPI specification
│   ├── museum-api.custom.yaml   # Optional customization
│   └── .cache/                  # Auto-generated cache
├── src/
│   └── server.ts               # Your server code
├── package.json                # {"type": "module"}
└── tsconfig.json               # ES2022 modules

🔐 Authentication

Supports HTTP Basic, Bearer tokens, and API keys:

# museum-api.custom.yaml
authenticationOverrides:
  - endpoint: "*"
    credentials:
      username: "${API_USERNAME}"
      password: "${API_PASSWORD}"

🧪 Testing

# Test tool generation
npm install -g @modelcontextprotocol/inspector
mcp-inspector npx openapi-mcp-bridge --definitions ./api-definitions

# Validate OpenAPI specs
npx @redocly/cli lint api-definitions/*.yaml

# Test with real API calls
node -e "
import { MCPClient } from '@modelcontextprotocol/client';
// ... client code
"

📝 Examples

• Express Integration
• Standalone Server
• CLI Usage
• Claude Desktop Setup
• Claude Code Integration
• Complete Museum API

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• OpenAPI Initiative for the OpenAPI specification
• ReadMe OpenAPI Parser for robust OpenAPI parsing

---

Need help? Check our troubleshooting guide or open an issue.