How do I use OpenAPI MCP Bridge?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenAPI MCP Bridge search for pet endpoints in petstore API" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OpenAPI MCP Bridge

by samuellawrence

Overview Schema Source Related Servers Discussions Admin

Python

Remote

OpenAPI MCP Bridge

A generic MCP server that takes any OpenAPI/Swagger specification and exposes it as MCP tools, allowing AI assistants to search, explore, and execute any REST API.

Architecture

                                    +------------------+
                                    |   Claude / AI    |
                                    +--------+---------+
                                             |
                                             | MCP Protocol
                                             v
+------------------------------------------------------------------+
|                      OpenAPI MCP Bridge                          |
|                                                                  |
|  +-------------+    +-------------+    +------------------+      |
|  |   Config    |    |   Parser    |    |    Registry      |      |
|  | (apis.json) |--->| (OpenAPI)   |--->| (API endpoints)  |      |
|  +-------------+    +-------------+    +------------------+      |
|                                                 |                |
|  +-------------+    +-------------+    +--------v---------+      |
|  | Guardrails  |    |   Search    |    |    Executor      |      |
|  | (safety)    |    |  (fuzzy)    |    |    (httpx)       |      |
|  +-------------+    +-------------+    +------------------+      |
|                                                 |                |
+------------------------------------------------------------------+
                                                  |
                                                  v
                                    +------------------+
                                    |    REST APIs     |
                                    | (Petstore, etc)  |
                                    +------------------+

Related MCP server: Swagger MCP

Quick Start

Installation

# Clone the repository
git clone https://github.com/your-username/openapi-mcp-bridge.git
cd openapi-mcp-bridge

# Install with uv
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"

Register an API

Edit config/apis.json to add your API:

{
  "apis": [
    {
      "name": "my-api",
      "spec_url": "https://api.example.com/openapi.json",
      "base_url": "https://api.example.com",
      "auth": {
        "type": "bearer",
        "token": "$MY_API_TOKEN",
        "header_name": "Authorization"
      },
      "settings": {
        "default_page_size": 20,
        "confirm_destructive": true
      }
    }
  ]
}

Xquik API Example

For a real authenticated OpenAPI 3.1 API, copy config/xquik.apis.example.json to your active config and set XQUIK_API_KEY. The example registers Xquik's public spec for X/Twitter automation, trends, tweet search, media, monitor, and webhook endpoints.

Run the Server

# Run with fuzzy search (default)
python -m src.server

# Run with embedding search (better semantic understanding)
python -m src.server --search-provider embedding

# Or set via environment variable
SEARCH_PROVIDER=embedding python -m src.server

Install Embedding Search (Optional)

For better semantic search using sentence-transformers:

# With uv
uv pip install "sentence-transformers>=2.2.0" "numpy>=1.24.0"

# Or with pip
pip install sentence-transformers numpy

Configuration Reference

API Configuration

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for the API
`spec_url`	string	Yes	URL or local path to OpenAPI spec
`base_url`	string	Yes	Base URL for API requests
`auth`	object	No	Authentication configuration
`settings`	object	No	API-specific settings

Authentication Types

Type	Description	Example
`bearer`	Bearer token in Authorization header	`Authorization: Bearer <token>`
`api_key`	API key in header or query param	`X-API-Key: <token>`
`basic`	Basic auth (base64 encoded)	`Authorization: Basic <base64>`
`none`	No authentication	-

Environment variables can be referenced with $VAR_NAME syntax.

Settings

Setting	Default	Description
`default_page_size`	20	Default limit for list responses
`max_batch_size`	50	Maximum requests in batch execution
`rate_limit_per_second`	5	Rate limiting for requests
`confirm_destructive`	true	Require confirmation for DELETE/PUT/PATCH

Search Providers

Fuzzy Search (Default)

Uses thefuzz library for string matching. Fast and works without additional dependencies.

python -m src.server --search-provider fuzzy

Best for: Exact keyword matching, operation IDs, path names.

Embedding Search

Uses sentence-transformers for semantic similarity. Better understanding of synonyms and intent.

python -m src.server --search-provider embedding

Best for: Natural language queries, synonym matching, semantic similarity.

Comparison:

Query	Fuzzy	Embedding
"find all pets"	High confidence	High confidence
"what animals are available"	Low confidence	High confidence
"buy a pet"	Mixed results	Finds store/order
"remove a specific animal"	Mixed results	Finds DELETE pet

Tool Reference

1. list_apis

List all registered OpenAPI/Swagger APIs.

Input: None

Output:

[
  {
    "name": "petstore",
    "base_url": "https://petstore.example.com",
    "description": "Pet Store API",
    "auth_type": "api_key",
    "endpoint_count": 15
  }
]

2. search_endpoints

Search for API endpoints by natural language description.

Input:

{
  "api": "petstore",
  "query": "find all available pets",
  "limit": 5
}

Output:

{
  "api": "petstore",
  "query": "find all available pets",
  "results": [
    {
      "endpoint": {
        "path": "/pet/findByStatus",
        "method": "GET",
        "summary": "Finds Pets by status",
        "parameters": [...]
      },
      "similarity_score": 0.85,
      "low_confidence": false
    }
  ],
  "total_results": 5
}

3. execute_endpoint

Execute an API endpoint.

Input:

{
  "api": "petstore",
  "path": "/pet/{petId}",
  "method": "GET",
  "params": {"petId": 123},
  "limit": 20,
  "offset": 0,
  "confirmed": false
}

Output:

{
  "status_code": 200,
  "data": {"id": 123, "name": "Buddy", "status": "available"},
  "truncated": false,
  "auth_error": false
}

For destructive operations (DELETE, PUT, PATCH), set confirmed: true.

4. batch_execute

Execute multiple API endpoints in parallel.

Input:

{
  "api": "petstore",
  "requests": [
    {"path": "/pet/1", "method": "GET"},
    {"path": "/pet/2", "method": "GET"},
    {"path": "/pet/3", "method": "GET"}
  ],
  "parallel": true,
  "confirmed": true
}

Output:

{
  "results": [...],
  "summary": {"total": 3, "succeeded": 3, "failed": 0}
}

Usage Examples

Example 1: Simple Query

User: What pets are available in the store?

AI: Let me search for that endpoint and get the data.
    1. search_endpoints(api="petstore", query="find available pets")
    2. execute_endpoint(api="petstore", path="/pet/findByStatus",
                        method="GET", params={"status": "available"})

    Result: Found 6 available pets: Buddy (dog), Whiskers (cat), ...

Example 2: Creating a Resource

User: Add a new pet named "Max" to the store.

AI: 1. search_endpoints(api="petstore", query="create new pet")
    2. execute_endpoint(api="petstore", path="/pet", method="POST",
                        body={"name": "Max", "species": "dog", "status": "available"})

    Result: Created pet with ID 15.

Example 3: Destructive Operation

User: Delete pet #15.

AI: 1. execute_endpoint(api="petstore", path="/pet/{petId}", method="DELETE",
                        params={"petId": 15}, confirmed=false)

    Warning: This is a destructive operation. Set confirmed=true to proceed.

User: Yes, go ahead.

AI: 2. execute_endpoint(..., confirmed=true)

    Result: Pet #15 deleted successfully.

Claude Desktop Integration

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

{
  "mcpServers": {
    "openapi-bridge": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/openapi-mcp-bridge",
      "env": {
        "PETSTORE_KEY": "your-api-key"
      }
    }
  }
}

Claude Code Integration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "openapi-bridge": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/openapi-mcp-bridge",
      "env": {
        "PETSTORE_KEY": "your-api-key"
      }
    }
  }
}

Testing

Run Unit Tests

pytest tests/test_parser.py tests/test_search.py tests/test_executor.py -v

Run Integration Tests

# Requires mock server to start automatically
pytest tests/test_integration.py -v

Start Mock Server Manually

cd mock-petstore
./run.sh

Development

Project Structure

openapi-mcp-bridge/
├── src/
│   ├── __init__.py
│   ├── server.py          # MCP server with 4 tools
│   ├── config.py          # Configuration loader
│   ├── parser.py          # OpenAPI spec parser
│   ├── registry.py        # API registry
│   ├── executor.py        # HTTP request executor
│   ├── guardrails.py      # Safety checks
│   └── search/
│       ├── base.py        # Search interface
│       ├── fuzzy.py       # Fuzzy search
│       └── embedding.py   # Embedding search (placeholder)
├── config/
│   └── apis.json          # API registrations
├── mock-petstore/         # Test server
├── tests/
└── pyproject.toml

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

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Swagger MCPOAuth
com.smartbear
MCP server for AI access to Swagger by SmartBear.
API Testing Documentation Access Developer Tools
144
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181

Related MCP Servers

OpenAPI to MCP Server
RAG Systems API Testing Developer Tools
TykTechnologies
A
license
D
quality
C
maintenance
A tool that creates MCP (Model Context Protocol) servers from OpenAPI/Swagger specifications, enabling AI assistants to interact with your APIs.
Updated a year ago (2025-06-27 14:17 UTC)
3
64 npm
49
MIT
Swagger MCP
API Testing Developer Tools RAG Systems
kyle-pena-nlp
F
license
Not graded
quality
D
maintenance
Automatically converts Swagger/OpenAPI specifications into MCP servers, enabling AI agents to interact with any REST API through natural language by exposing endpoints as AI-friendly tools.
Updated a year ago (2025-08-05 20:59 UTC)
3
-
OpenAPI MCP Server
API Testing Developer Tools App Automation
cloudwarriors-ai
A
license
A
quality
D
maintenance
A generic MCP server that dynamically exposes any OpenAPI-documented REST API to LLMs by auto-discovering endpoints. It provides tools for exploring API capabilities and making authenticated requests directly through natural language interfaces.
Updated 8 months ago (2026-01-27 03:22 UTC)
2
7 npm
MIT
anyapi-mcp-server
API Testing Developer Tools RAG Systems
quiloos39
A
license
Not graded
quality
D
maintenance
A universal MCP server that connects any REST API to AI assistants via OpenAPI or Postman specifications. It enables dynamic tool creation with GraphQL-style field selection and automatic schema inference for efficient data retrieval.
Updated 5 months ago (2026-04-13 18:26 UTC)
8 npm
6
-

OpenAPI MCP Bridge

Architecture

Quick Start

Installation

Register an API

Xquik API Example

Run the Server

Install Embedding Search (Optional)

Configuration Reference

API Configuration

Authentication Types

Settings

Search Providers

Fuzzy Search (Default)

Embedding Search

Tool Reference

1. list_apis

2. search_endpoints

3. execute_endpoint

4. batch_execute

Usage Examples

Example 1: Simple Query

Example 2: Creating a Resource

Example 3: Destructive Operation

Claude Desktop Integration

Claude Code Integration

Testing

Run Unit Tests

Run Integration Tests

Start Mock Server Manually

Development

Project Structure

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

OpenAPI to MCP Server

Swagger MCP

OpenAPI MCP Server

anyapi-mcp-server