specbridge

SpecBridge is an MCP server that converts OpenAPI specifications into MCP tools. It monitors a folder full of OpenAPI spec files and automatically generates a set of MCP-compatible tools from each spec. Each tool is named to reflect its API and operation (e.g., example_getUser or github_get_user_repos) and can be accessed via the MCP client with either stdio or HTTP streaming transports. The server also supports auto authentication by reading credentials from a .env file in your specs folder, using patterns like {API_NAME}_API_KEY, {API_NAME}_TOKEN, or {API_NAME}_USERNAME/{API_NAME}_PASSWORD, so you can securely call the generated tools without embedding credentials in your requests. You can list loaded specs and their tools with the built-in list command to verify what’s loaded and available.

To use SpecBridge, drop your OpenAPI spec files (.json, .yaml, .yml) into a designated specs folder, place an optional .env file with credentials in that folder, then start the server. If you’ve installed SpecBridge globally, you can start it with specbridge (or use npx as shown in the configuration). Use the MCP client to connect to the server and interact with the generated tools. You can also run the CLI with a custom specs folder (specbridge --specs /path/to/specs) or enable HTTP transport (specbridge --transport httpStream --port 8080) for streaming access.

The tools are automatically named and exposed for each operation in your OpenAPI specs, following either the operationId (api_operation) or a derived name from the path and method if no operationId exists.

Prerequisites:

• Node.js (recommended >= 14) and npm installed on your machine
• Access to the internet to install dependencies

Installation steps:

1. Install SpecBridge globally (optional but convenient):

npm install -g specbridge

2. Prepare a specs folder where you will place your OpenAPI spec files (e.g., ~/mcp-apis). Each file will be read to generate tools.

3. Start the server (specify your specs folder with --specs if not using the default location):

# Default stdio transport, using the current directory
specbridge

# With a custom specs folder
specbridge --specs ~/mcp-apis

# Enable HTTP streaming transport on port 8080
specbridge --transport httpStream --port 8080

4. Verify loaded specs and tools:

specbridge list

If you prefer not to install globally, you can also run via npx without installation:

npx -y specbridge --specs /absolute/path/to/your/specs

Tips and common issues:

• Absolute paths tend to work more reliably for the --specs argument and other file paths; avoid spaces in paths when possible.
• Place a .env file inside your specs folder to configure per-API credentials using the patterns described in the docs (e.g., PETSTORE_API_KEY, GITHUB_TOKEN).
• The server automatically namespaces tools based on the API name derived from the spec filename, and follows the naming conventions described in the README (operationId-based naming when available).
• If you add or update specs, restart the MCP server to ensure tools reflect the latest changes. Use specbridge list to confirm the current state.
• The server supports both stdio and HTTP streaming transports, so you can integrate with different MCP clients as needed.
• If authentication isn’t working, double-check your .env filename, variable names, and ensure they match the spec’s derived API name.