OpenAPI to MCP Conversion Architecture Specification

#1. The Challenge of Manual MCP Server Development

With tens of thousands of developer APIs in production today, manually authoring, testing, and maintaining dedicated native MCP server wrappers for every service is inefficient and error-prone.

However, the vast majority of modern enterprise REST APIs already publish formal OpenAPI (Swagger) v3.0 and v3.1 specifications. The MCP Bridge converter automates this entire pipeline by parsing OpenAPI definitions and generating fully typed Model Context Protocol stdio/SSE server configs in under 50 milliseconds.

By treating OpenAPI definitions as the authoritative source of truth, developers gain instant AI access to internal microservices, SaaS APIs, and cloud infrastructures without writing boilerplate code.

#2. The Translation Pipeline: OpenAPI to JSON-RPC Tools

The MCP Bridge conversion engine processes OpenAPI specifications through a multi-stage compilation pipeline:

1. Path & Operation Extraction: The parser traverses paths, HTTP methods (GET, POST, PUT, PATCH, DELETE), and extracts operationId, summary, and description.

2. Operation ID Normalization: If an operationId is missing, the engine generates a deterministic identifier following the convention <service>_<method>_<path_slug>.

3. Parameter Schema Conversion: Query parameters, path variables, header parameters, and JSON request bodies are converted into strict JSON Schema inputSchema definitions.

4. Security Scheme Mapping: OpenAPI securitySchemes (Bearer Tokens, API Key Headers, Basic Auth) are mapped to required client env variables.

{
  "name": "create_payment_intent",
  "description": "Creates a new Stripe Payment Intent payload.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "integer",
        "description": "Amount in cents to charge (e.g. 2000 for $20.00)."
      },
      "currency": {
        "type": "string",
        "description": "Three-letter ISO currency code (e.g. 'usd', 'eur')."
      },
      "payment_method_types": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Allowed payment method types."
      }
    },
    "required": [
      "amount",
      "currency"
    ]
  }
}

Copy

#3. Compilation Pipeline Architecture

The conversion engine operates entirely within the browser via WebAssembly and TypeScript, transforming raw REST API specifications into Model Context Protocol primitives without uploading private schemas to external servers.

The following architectural diagram illustrates the end-to-end AST compilation flow:

+--------------------------------------------------------------------+
|               MCP Bridge OpenAPI Compilation Pipeline              |
+--------------------------------------------------------------------+
|  OpenAPI 3.0 / 3.1 Spec (YAML or JSON)                             |
+--------------------------------------------------------------------+
                                |
                                v
+--------------------------------------------------------------------+
|  1. AST Parser & Schema Normalizer                                 |
|     - Resolves external and local $ref pointers                     |
|     - Normalizes complex type unions and nullable fields           |
+--------------------------------------------------------------------+
                                |
                                v
+--------------------------------------------------------------------+
|  2. Endpoint Tree Shaking & Method Filtering                       |
|     - Filters operations by category tags (e.g. 'billing', 'auth')  |
|     - Prunes destructive HTTP methods (DELETE, PUT) for safe modes |
+--------------------------------------------------------------------+
                                |
                                v
+--------------------------------------------------------------------+
|  3. JSON Schema inputSchema Compiler                               |
|     - Combines path, query, header, and body schemas into single   |
|       unified JSON Schema Draft-07 inputSchema object              |
+--------------------------------------------------------------------+
                                |
                                v
+--------------------------------------------------------------------+
|  4. Protocol Emitter & Runtime Dispatcher                          |
|     - Emits tools/list tool declarations                           |
|     - Configures @modelcontextprotocol/server-openapi stdio bridge  |
+--------------------------------------------------------------------+

Copy

#4. Tree-Shaking & Large API Optimization

Massive OpenAPI specifications (such as AWS, GitHub, or Azure containing thousands of endpoints) can overwhelm an LLM's context window if all tools are injected simultaneously.

The MCP Bridge conversion engine incorporates intelligent endpoint filtering and tree-shaking:

• Category & Tag Filtering: Group operations by resource tags (e.g. users, billing, repos) to generate lightweight, specialized MCP server subsets.

• Method Pruning: Optionally exclude destructive HTTP methods (DELETE, PUT) for read-only or diagnostic monitoring workflows.

• Context Budgeting: Estimates the total token footprint of the generated tool schemas to ensure the assistant retains ample room for conversational memory and reasoning traces.

#5. Runtime Execution with @modelcontextprotocol/server-openapi

Generated MCP configurations execute locally using the official @modelcontextprotocol/server-openapi runtime adapter. The adapter runs as a lightweight Node.js child process that translates incoming JSON-RPC tools/call requests into standard HTTP requests dispatched to the upstream API.

Authentication credentials configured in the client's env dictionary are injected directly into outgoing HTTP Authorization headers, ensuring complete security isolation without routing credentials through cloud proxies.

{
  "mcpServers": {
    "api-service": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-openapi",
        "https://api.example.com/openapi.json"
      ],
      "env": {
        "API_KEY": "secret_token_here"
      }
    }
  }
}

Copy

#6. Handling Polymorphic Schemas and Multipart Payloads

Enterprise OpenAPI specifications often feature complex polymorphic schemas using anyOf, oneOf, or allOf inheritance, as well as multipart/form-data file uploads. The MCP Bridge converter normalizes these structures into LLM-friendly schemas.

For polymorphic objects, discriminator properties are promoted to required enum fields so the language model unambiguously identifies which payload variant to generate. Binary file uploads are converted to Base64-encoded string parameters accompanied by descriptive format annotations.