> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
# 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`:

```json theme={null}
{
  "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

<Steps>
  <Step title="Start the Petstore demo backend">
    The example uses the official Swagger Petstore Docker image:

    ```bash theme={null}
    docker compose up
    ```

    This starts the Petstore application on `localhost:8080`.
  </Step>

  <Step title="Start agentgateway">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Connect with MCP Inspector">
    ```bash theme={null}
    npx @modelcontextprotocol/inspector
    ```

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

  <Step title="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.
  </Step>
</Steps>

## 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:

```yaml theme={null}
targets:
- name: my-api
  openapi:
    schema:
      file: ./my-api-schema.json
    host: api.example.com:443
```

<Tip>
  For HTTPS backends, combine with [backend TLS configuration](/guides/tls#backend-tls) to enforce certificate verification.
</Tip>

## CORS for browser-based clients

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

```yaml theme={null}
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

<CardGroup cols={2}>
  <Card title="Tool name" icon="tag">
    Derived from the `operationId` field. Falls back to `{method}_{path}` if `operationId` is absent.
  </Card>

  <Card title="Tool description" icon="file-lines">
    Populated from the operation's `summary` and `description` fields.
  </Card>

  <Card title="Input schema" icon="code">
    Constructed from the operation's `parameters` (query, path, header) and `requestBody` JSON schema.
  </Card>

  <Card title="HTTP mapping" icon="arrow-right-arrow-left">
    Agentgateway maps tool call arguments back to the correct HTTP method, path parameters, query strings, and request body.
  </Card>
</CardGroup>

## Testing with MCP Inspector

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

```bash theme={null}
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.

<Note>
  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.
</Note>