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 (optional)

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:

If installed on your machine:

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

Otherwise:

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

💻 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.