Specbridge: OpenAPI to MCP Server Tools

Overview

Specbridge converts OpenAPI documents into ready-to-run Model Context Protocol (MCP) server tools. Given a single OpenAPI v3 (or v2) specification, Specbridge generates endpoint handlers, request/response validation, mock responses, and deployment artifacts so you can run an MCP-compatible tool in minutes. The goal is to turn an API contract into a reproducible, validated runtime that can be used for rapid prototyping, testing, or production integration with minimal manual wiring.

By automating the translation from OpenAPI to MCP, Specbridge enforces consistent validation logic, schema-driven documentation, and predictable tooling. This reduces the boilerplate of building adapters and lets teams focus on the model and workflow logic that interacts with the API rather than on plumbing and repeatable validation code.

Features

• Generate MCP-compatible server tools directly from OpenAPI specs
• Schema-driven request/response validation (JSON Schema / OpenAPI)
• Auto-generated mock responses and example-based stubs
• Optionally generate authentication and header injection code
• CLI and Docker-friendly workflows for CI/CD
• Output includes Dockerfile, Kubernetes manifests, and simple deployment scripts
• Customizable templates and plugin hooks for platform-specific behavior
• Lightweight runtime with metrics and basic logging to fit MCP environments

Installation / Configuration

Clone and run from source (recommended when experimenting):

git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install
# run the CLI from source
node ./bin/specbridge.js convert -i ./openapi.yaml -o ./out

Run using npm (if distributed via npm):

# install globally
npm install -g specbridge
# convert OpenAPI to MCP tool
specbridge convert --input openapi.yaml --output ./mcp-tool

Docker-based execution:

# build an image that contains the CLI (optional)
docker build -t specbridge .
# run the converter in a container, mounting input and output
docker run --rm -v $(pwd)/openapi.yaml:/work/openapi.yaml -v $(pwd)/out:/work/out specbridge \
  convert /work/openapi.yaml /work/out

A minimal config file (specbridge.config.json) to control generation:

{
  "toolId": "payments-proxy",
  "version": "0.1.0",
  "basePath": "/api",
  "mcp": {
    "listenPort": 8080,
    "strictValidation": true
  },
  "templates": {
    "handler": "templates/custom-handler.js"
  }
}

CLI usage summary:

specbridge convert --input openapi.yaml \
                  --output ./mcp-tool \
                  --config specbridge.config.json

Available Resources

Specbridge produces a small set of well-structured artifacts suitable for immediate deployment or customization:

Additionally, Specbridge exposes hooks for providing custom templates and post-generation scripts so teams can integrate company-specific middleware (auth, tracing, metrics).

Use Cases

• Rapid frontend-backend integration
  • Generate a mock MCP tool from the API spec to unblock frontend development while backend services are under development. The generated mocks follow the contract and can be swapped for real implementations later.
• Contract-driven CI testing
  • Use generated validators in your CI to assert that service responses conform to the OpenAPI contract. Run the MCP tool in CI as a contract gate.
• Microservice prototyping
  • Quickly scaffold a lightweight MCP server that implements all declared endpoints; implement only the business logic and reuse generated validation and deployment artifacts.
• API gateway adapters
  • Create an MCP-compatible adapter that translates between internal model context messages and external REST endpoints, with automatic header mapping and input sanitization.
• Compliance and auditing
  • Ensure requests/responses adhere to schema constraints and generate logs/metrics for audit trails with minimal hand coding.

Quick Example — Generated Handler Snippet

A generated JavaScript handler (simplified) might look like:

module.exports = async function handleRequest(ctx) {
  // ctx.request contains validated body/params
  const { params, body, headers } = ctx.request;
  // implement business logic or call downstream service
  const result = await callPaymentService(body);
  return {
    status: 200,
    body: result
  };
};

This handler is wrapped by the generated MCP server that performs validation, error mapping, and lifecycle management.

Next Steps

• Prepare a focused OpenAPI spec: ensure examples are set for better mocks.
• Try generating a tool locally and inspect the validators and mocks.
• Customize templates to match your runtime conventions (auth, tracing).
• Integrate the generated Dockerfile into your CI/CD pipeline for automated deployment.