Specbridge

An MCP server that turns OpenAPI specifications into MCP tools. Scan a folder for OpenAPI spec files and automatically generate corresponding tools. No configuration files, no separate servers - just drop specs in a folder and get tools.

Built with FastMCP for TypeScript.

✨ Features

🎯 Zero Configuration: Filesystem is the interface - just drop OpenAPI specs in a folder
🔐 Auto Authentication: Simple .env file with {API_NAME}_API_KEY pattern
🏷️ Namespace Isolation: Multiple APIs coexist cleanly (e.g., petstore_getPet, github_getUser)
📝 Full OpenAPI Support: Handles parameters, request bodies, authentication, and responses
🚀 Multiple Transports: Support for stdio and HTTP streaming
🔍 Built-in Debugging: List command to see loaded specs and tools

🚀 Quick Start

1️⃣ Install

npm install -g specbridge

2️⃣ Create a specs folder

mkdir ~/mcp-apis

3️⃣ Add OpenAPI specs

Drop any .json, .yaml, or .yml OpenAPI specification files into your specs folder:

# Example: Download the Petstore spec
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4️⃣ Configure authentication (optional)

Create a .env file in your specs folder:

# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key

5️⃣ Add to MCP client configuration

For Claude Desktop or Cursor, add to your MCP configuration:

{
  "mcpServers": {
    "specbridge": {
      "command": "specbridge",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

6️⃣ Restart your MCP client

That's it! Your OpenAPI specs are now available as MCP tools. ✅

💻 CLI Usage

🚀 Start the server

# Default: stdio transport, current directory
specbridge

# Custom specs folder
specbridge --specs ~/my-api-specs

# HTTP transport mode
specbridge --transport httpStream --port 8080

📋 List loaded specs and tools

# List all loaded specifications and their tools
specbridge list

# List specs from custom folder
specbridge list --specs ~/my-api-specs

🔑 Authentication Patterns

The server automatically detects authentication from environment variables using these patterns:

Pattern	Auth Type	Usage
`{API_NAME}_API_KEY`	🗝️ API Key	`X-API-Key` header
`{API_NAME}_TOKEN`	🎫 Bearer Token	`Authorization: Bearer {token}`
`{API_NAME}_BEARER_TOKEN`	🎫 Bearer Token	`Authorization: Bearer {token}`
`{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD`	👤 Basic Auth	`Authorization: Basic {base64}`

The {API_NAME} is derived from the filename of your OpenAPI spec:

petstore.json → PETSTORE_API_KEY
github-api.yaml → GITHUB_TOKEN
my_custom_api.yml → MYCUSTOMAPI_API_KEY

🏷️ Tool Naming

Tools are automatically named using this pattern:

With operationId: {api_name}_{operationId}
Without operationId: {api_name}_{method}_{path_segments}

Examples:

petstore_getPetById (from operationId)
github_get_user_repos (generated from GET /user/repos)

📁 File Structure

your-project/
├── api-specs/           # Your OpenAPI specs folder
│   ├── .env            # Authentication credentials
│   ├── petstore.json   # OpenAPI spec files
│   ├── github.yaml     # 
│   └── custom-api.yml  # 
└── mcp-config.json     # MCP client configuration

📄 Example OpenAPI Spec

Here's a minimal example that creates two tools:

# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created

This creates tools named:

example_getUser
example_createUser

🔧 Troubleshooting

❌ No tools appearing?

Check that your OpenAPI specs are valid:
specbridge list --specs /path/to/specs
Ensure files have correct extensions (.json, .yaml, .yml)
Check the server logs for parsing errors

⚠️ Note: Specbridge works best when you use absolute paths (with no spaces) for the --specs argument and other file paths. Relative paths or paths containing spaces may cause issues on some platforms or with some MCP clients.

🔐 Authentication not working?

Verify your .env file is in the specs directory
Check the naming pattern matches your spec filename
Use the list command to verify auth configuration:
specbridge list

🔄 Tools not updating after spec changes?

Restart the MCP server to reload the specs
Check file permissions
Restart the MCP client if needed

🛠️ Development

# Clone and install
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# Build
npm run build

# Test locally
npm run dev -- --specs ./examples

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server that automatically converts OpenAPI specifications into MCP tools by scanning a folder for spec files, requiring no configuration files or separate servers.

Related MCP Servers

MCP-OpenAPI
rmasters
-
security
A
license
-
quality
An MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
Last updated -
2
Python
MIT License
Emcee
loopwork-ai
-
security
A
license
-
quality
Generate an MCP server for any OpenAPI documented endpoint.
Last updated -
201
Go
Apache 2.0
OpenAPI MCP Server
JacerOmri
-
security
A
license
-
quality
A command-line tool that transforms any OpenAPI service into a Model Context Protocol (MCP) server, enabling seamless integration with AI agents and tools that support the MCP specification.
Last updated -
90
2
TypeScript
MIT License
OpenAI API MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
An auto-generated MCP server that enables interaction with the OpenAI API, allowing users to access OpenAI's models and capabilities through the Multi-Agent Conversation Protocol.
Last updated -
Python

View all related MCP servers