OpenAPI to MCP

Transform any OpenAPI specification into MCP tools, making REST APIs accessible to agentic workflows.

Agentgateway can convert any OpenAPI 3.x specification into MCP tools. Each HTTP operation defined in the spec becomes a callable MCP tool, giving AI agents structured access to existing REST APIs without any code changes.

How it works

When you point agentgateway at an OpenAPI schema, it reads every path and method, derives a tool name from the operationId (or the path and method), and exposes those tools over MCP. Requests from MCP clients are translated to HTTP calls and forwarded to the backend host you configure.

MCP client  →  agentgateway  →  OpenAPI tool mapping  →  REST backend

Configuration

Add an openapi target to your backend configuration:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: openapi
            openapi:
              schema:
                file: ./examples/openapi/openapi.json
              host: localhost:8080
      policies:
        cors:
          allowOrigins:
          - "*"
          allowHeaders:
          - content-type
          - mcp-protocol-version
          - mcp-session-id
          exposeHeaders:
          - mcp-session-id
          - mcp-protocol-version
          maxAge: 5m

Key fields

Field	Description
openapi.schema.file	Path to the OpenAPI JSON or YAML specification file
openapi.host	The backend host (and optional port) to forward requests to

OpenAPI schema structure

The schema file follows the OpenAPI 3.x format. Agentgateway reads the paths object and uses operationId as the MCP tool name. Here is a snippet from the Petstore example used in examples/openapi/openapi.json:

{
  "openapi": "3.0.4",
  "info": {
    "title": "Swagger Petstore - OpenAPI 3.0",
    "version": "1.0.26"
  },
  "servers": [
    { "url": "/api/v3" }
  ],
  "paths": {
    "/pet": {
      "put": {
        "operationId": "updatePet",
        "summary": "Update an existing pet.",
        ...
      },
      "post": {
        "operationId": "addPet",
        "summary": "Add a new pet to the store.",
        ...
      }
    },
    "/store/order": {
      "post": {
        "operationId": "placeOrder",
        "summary": "Place an order for a pet.",
        ...
      }
    }
  }
}

Each operationId becomes the name of an MCP tool. Tool descriptions come from the summary and description fields. Input schemas are derived from the operation’s requestBody and parameters.

Running the Petstore example

1. Start the Petstore demo backend

   The example uses the official Swagger Petstore Docker image:

   docker compose up
   

   This starts the Petstore application on localhost:8080.

2. Start agentgateway

   cargo run -- -f examples/openapi/config.yaml
   

   Agentgateway reads examples/openapi/openapi.json and exposes every Petstore operation as an MCP tool on port 3000.

3. Connect with MCP Inspector

   npx @modelcontextprotocol/inspector
   

   Navigate to the URL printed in the terminal, then connect to http://localhost:3000.

4. Browse and call tools

   Open the Tools tab in the inspector. You should see all Petstore operations listed as callable tools — updatePet, addPet, placeOrder, findPetsByStatus, and more.

   Select placeOrder, fill in the required fields, and click Call Tool to send a real order to the Petstore backend.

Connecting to a remote OpenAPI backend

Replace the host value with your backend’s address. The schema file can be a local path or fetched separately:

targets:
- name: my-api
  openapi:
    schema:
      file: ./my-api-schema.json
    host: api.example.com:443

For HTTPS backends, combine with backend TLS configuration to enforce certificate verification.

CORS for browser-based clients

When connecting from browser-based MCP clients (such as the MCP Inspector), enable CORS on the route:

policies:
  cors:
    allowOrigins:
    - "*"
    allowHeaders:
    - content-type
    - mcp-protocol-version
    - mcp-session-id
    exposeHeaders:
    - mcp-session-id
    - mcp-protocol-version
    maxAge: 5m

How REST endpoints become MCP tools

Tool name

Derived from the operationId field. Falls back to {method}_{path} if operationId is absent.

Tool description

Populated from the operation’s summary and description fields.

Input schema

Constructed from the operation’s parameters (query, path, header) and requestBody JSON schema.

HTTP mapping

Agentgateway maps tool call arguments back to the correct HTTP method, path parameters, query strings, and request body.

Testing with MCP Inspector

The MCP Inspector is the recommended tool for verifying your OpenAPI integration:

npx @modelcontextprotocol/inspector

1. Connect to http://localhost:3000 (or your listener address).
2. Navigate to the Tools tab to see all generated tools.
3. Select any tool, review its generated input schema, and invoke it.
4. Check the Response panel for the result from the upstream API.

The MCP Inspector does not support TLS with self-signed certificates. If your listener uses HTTPS, use a CA-signed certificate or test with curl directly.