For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Expose OpenAPI endpoints as MCP tools in the agentgateway UI playground

Expose an OpenAPIOpenAPIA specification for describing RESTful APIs. Agentgateway can connect to MCP servers that expose an OpenAPI specification. server on the agentgateway. Then, your OpenAPI endpoints become available as tools in the agentgateway UI playground.

Before you begin

1. Install the agentgateway binary.
2. Install the uv Python package manager.
3. Make sure that you have docker, such as by installing Docker Desktop.
4. For ARM64 machines: Install maven to build the sample Petstore image from source.

Set up your OpenAPI server

Start by setting up your OpenAPI server. You need an OpenAPI spec, such as a JSON or YAML file, as well as a running server instance that hosts the API. These steps use the Swagger Petstore server as an example.

In your OpenAPI schema, make sure to set the URL of the server. If no URL is set, agentgateway defaults to /. Then, the paths in your OpenAPI schema get an extra slash concatenated, which can break requests. For example, /api/v1/ becomes //api/v1/.

To avoid this issue, explicitly set the URL value to / in the OpenAPI schema, such as the following example.

 "servers": [
    {
      "url": "/"
    }
  ]

Sample Petstore server

Run the sample Swagger Petstore server locally. The following steps show use Docker and Maven as an example to pull, build, and run the Petstore server. You can also use your own OpenAPI server and update the steps accordingly.

Configure the agentgateway

From the directory where you plan to run agentgateway, download and review the OpenAPI schema for the Petstore server.

curl http://localhost:8080/api/v3/openapi.json > openapi.json

Then, connect agentgateway to the Petstore server. You can use the UI or a configuration file.

Verify access to the Petstore APIs

1. Open the agentgateway UI to view your listener and backend configuration.

2. From the navigation menu under MCP, click Tool Playground.

3. If you see a banner prompting you to allow browser access, click Apply CORS. This adds the UI’s origin to the MCP CORS policy so the playground can open a session, and the configuration reloads automatically.

4. Click Initialize. The agentgateway UI opens an MCP session and lists the Petstore operations from the OpenAPI spec as tools.

5. Verify that the Result panel reports the discovered tools, such as getPetById, findPetsByStatus, and addPet. Agentgateway generates one tool per operation in the spec, named after the operation’s operationId.

   

   

6. Verify access to a Petstore API.

   1. From the Tool dropdown, select the getInventory tool, which returns the store’s pet inventory by status and takes no parameters.

   2. Click Call tool.

   3. Verify that the Result panel returns HTTP 200 and the inventory counts in the Tool output.

      

      

Tool names

Agentgateway generates one MCP tool for each operation in your OpenAPI spec. Each tool is named after the operation’s operationId field. For example, an operation with operationId: addPet becomes an MCP tool named addPet. Make sure each operation in your spec defines a unique operationId so that the generated tool names are predictable and do not collide.

Tool response content

Agentgateway converts OpenAPI responses into MCP tool results or errors based on HTTP status. The Content-Type header and body determine the result content.

Binary responses without a Content-Type header use application/octet-stream.

Agentgateway treats a body as text if either condition holds:

• The Content-Type is text/*, has a json, xml, or yaml subtype or suffix, or is application/javascript, application/x-www-form-urlencoded, or application/x-ndjson.
• The body is valid UTF-8 and contains no NUL bytes, regardless of Content-Type.

For example, image/svg+xml is text because of its xml suffix. Agentgateway first tries to parse all text bodies as JSON, including those labeled text/plain.

Error responses

The status code changes the result as follows:

• 5xx responses: The client receives HTTP 500 with JSON-RPC error code -32603 (internal error) and message failed to send message. Agentgateway logs the upstream status and body.
• All other responses, including 4xx: The client receives a tool result with the content types described above. The result sets isError to false and omits the HTTP status code.

To help a model recognize a failed call, return an error body that describes the failure.

Example tool results

These examples show how upstream responses map to MCP tool results.

• A 200 response with Content-Type: application/json and a JSON object body:

  {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"available\":7,\"pending\":2,\"sold\":1}"}],"structuredContent":{"available":7,"pending":2,"sold":1},"isError":false}}

• A 200 response with Content-Type: application/json and a JSON array body:

  {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"data\":[\"cat\",\"dog\"]}"}],"structuredContent":{"data":["cat","dog"]},"isError":false}}

• A 200 response with Content-Type: text/plain and the body OK:

  {"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"OK"}],"isError":false}}

• A 200 response with Content-Type: image/png:

  {"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"image","data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAA=","mimeType":"image/png"}],"isError":false}}

• A 200 response with Content-Type: audio/wav:

  {"jsonrpc":"2.0","id":6,"result":{"content":[{"type":"audio","data":"UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=","mimeType":"audio/wav"}],"isError":false}}

• A 200 response with Content-Type: application/pdf from the getReport tool:

  {"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"resource","resource":{"uri":"tool://getReport","mimeType":"application/pdf","blob":"JVBERi0xLjQKJeLjz9MK"}}],"isError":false}}

• A 204 response with an empty body:

  {"jsonrpc":"2.0","id":8,"result":{"content":[],"isError":false}}

• A 404 response with Content-Type: text/plain and the body Pet not found:

  {"jsonrpc":"2.0","id":9,"result":{"content":[{"type":"text","text":"Pet not found"}],"isError":false}}

• A 500 response:

  {"jsonrpc":"2.0","id":10,"error":{"code":-32603,"message":"failed to send message"}}

Path parameters

OpenAPI path parameters are always required. In the MCP tool schema, each OpenAPI path parameter is required, even when the OpenAPI document omits required or sets it to false.

When a tool call fills a path parameter, the value must be a string or number. String values are percent-encoded before the request is forwarded to the upstream OpenAPI server.

Agentgateway rejects the tool call before it sends any request to the upstream server in the following cases:

• A required path parameter value is missing.
• A path parameter value is empty.
• A path parameter value is neither a string nor a number.
• A string value contains an empty, ., or .. path segment when split on / or \.

The client receives HTTP 500 with JSON-RPC error code -32603 (internal error) and message failed to send message:

{"jsonrpc":"2.0","id":2,"error":{"code":-32603,"message":"failed to send message"}}

The agentgateway log identifies the parameter and cause. For example:

error="mcp: failed to send message: invalid request: path parameter 'petId' is missing"

Other configurations

Schema URL

Fetch the OpenAPI schema from a remote URL. Agentgateway retrieves the schema at startup.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    cors:
      allowOrigins:
        - "*"
      allowHeaders:
        - "*"
  targets:
  - name: openapi
    openapi:
      schema:
        url: http://localhost:8080/api/v3/openapi.json
      host: localhost:8080

Inline schema

Embed the OpenAPI schema directly as an inline string.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    cors:
      allowOrigins:
        - "*"
      allowHeaders:
        - "*"
  targets:
  - name: openapi
    openapi:
      schema: |
        {
          "openapi": "3.0.0",
          "info": { "title": "Petstore", "version": "1.0.0" },
          "servers": [{ "url": "/" }],
          "paths": {
            "/pet/{petId}": {
              "get": {
                "operationId": "getPetById",
                "summary": "Find pet by ID",
                "parameters": [
                  {
                    "name": "petId",
                    "in": "path",
                    "required": true,
                    "schema": { "type": "integer", "format": "int64" }
                  }
                ],
                "responses": { "200": { "description": "successful operation" } }
              }
            }
          }
        }
      host: localhost:8080

Override the schema server path

By default, operation paths use the path from the OpenAPI schema’s server URL. To replace that prefix without editing the schema, set a non-root path in the target’s host URI. If the target uses host/port/path or backend, set path instead.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  targets:
  - name: openapi
    openapi:
      host: https://example.com/api
      schema:
        url: https://example.com/openapi.json

With this configuration, an operation at /users is forwarded to https://example.com/api/users. Config validation rejects paths that do not start with a single /. Validation also rejects paths that contain a query string, fragment, or backslash.

If the path is omitted, empty, or /, the target keeps using the schema’s server path. To route to root when the schema has a server path, update the schema’s server URL to /.

Stateless sessions

OpenAPI backends are inherently stateless because they translate standard REST endpoints into MCP tools. You can set statefulMode: stateless on the MCP backend to skip session tracking. In stateless mode, the gateway automatically wraps each request with an initialization sequence so the upstream processes every request independently.

mcp:
  port: 3000
  statefulMode: stateless
  targets:
  - name: openapi
    openapi:
      schema:
        url: http://localhost:8080/api/v3/openapi.json
      host: localhost:8080