Skip to main content
Glama

Specbridge

Verified on MseeP smithery badge

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?

  1. Check that your OpenAPI specs are valid:

    specbridge list --specs /path/to/specs
  2. Ensure files have correct extensions (.json, .yaml, .yml)

  3. 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?

  1. Verify your .env file is in the specs directory

  2. Check the naming pattern matches your spec filename

  3. Use the list command to verify auth configuration:

    specbridge list

πŸ”„ Tools not updating after spec changes?

  1. Restart the MCP server to reload the specs

  2. Check file permissions

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

Related MCP Servers

  • -
    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 -
    8
    MIT License
  • -
    security
    A
    license
    -
    quality
    Generate an MCP server for any OpenAPI documented endpoint.
    Last updated -
    303
    MIT License
    • Apple
    • Linux
  • -
    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 -
    73
    5
    MIT License
  • -
    security
    F
    license
    -
    quality
    A tool that accelerates MCP protocol adoption by automatically generating MCP-compatible server components from OpenAPI specifications, enabling seamless integration with existing services as a sidecar.
    Last updated -
    4

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TBosak/specbridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server