OpenAPI Tool

Automatically generate tools from an OpenAPI specification.

Overview

The OpenAPI tool fetches an OpenAPI 3.x specification from a URL and creates one tool per API operation. Each endpoint's parameters, request body, and description are translated into a callable tool that the agent can invoke directly.

Configuration

toolsets:
  - type: openapi
    url: "https://petstore3.swagger.io/api/v3/openapi.json"

With custom headers

Pass custom headers to every HTTP request made by the generated tools (for example, for authentication):

toolsets:
  - type: openapi
    url: "https://api.example.com/openapi.json"
    headers:
      Authorization: "Bearer ${env.API_TOKEN}"
      X-Custom-Header: "my-value"

Custom timeout

Override the default 30-second HTTP timeout (applies both to fetching the spec and to the generated tool calls):

toolsets:
  - type: openapi
    url: "https://api.example.com/openapi.json"
    timeout: 60

Reaching internal services

By default, the OpenAPI tool's direct path refuses connections to non-public IP addresses, including a public hostname that resolves to an internal address. Docker Agent does not evaluate PAC, so the dial-time guard applies when Docker Desktop is unavailable or bypassed; egress selected by Docker Desktop — through a proxy or with PAC DIRECT — is outside local dial-time enforcement. Opt in with allow_private_ips when the spec or its servers entries legitimately target localhost or your internal network:

toolsets:
  - type: openapi
    url: "http://localhost:8080/openapi.json"
    allow_private_ips: true

When Docker Desktop is running, eligible public destinations use its PAC proxy before standard environment-proxy routing. A PAC DIRECT response selects Docker Desktop's direct egress. NO_PROXY does not bypass Desktop PAC selection; set DOCKER_AGENT_DISABLE_DESKTOP_PROXY=1 (or true, yes, or on) to bypass only the Desktop adapter per request and restore standard HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY routing. Loopback always stays direct. For guarded requests, Docker Desktop PAC routing is restricted to Docker-owned hostnames (docker.com and docker.io families); all other hosts use the direct SSRF-guarded path. Within the allowed set, local DNS preflight requires public addresses before Docker Desktop is selected; all lookup failures — including NXDOMAIN, empty results, errors, and private or mixed answers — stay on the SSRF-protected direct path. This preflight does not validate Docker Desktop-selected egress, whether PAC selects a proxy or DIRECT. allow_private_ips: true removes that direct-path guard for trusted internal services, but Desktop PAC still takes precedence for eligible non-loopback destinations. See Docker Desktop proxy.

Properties

How it works

1. The spec is fetched from the configured url at startup.
2. Each operation (GET, POST, PUT, …) becomes a separate tool named after its operationId (or method_path when no operationId is set).
3. Path and query parameters are exposed as tool parameters. Request body properties are prefixed with body_.
4. Read-only operations (GET, HEAD, OPTIONS) are annotated accordingly.
5. Responses are returned as text; errors include the HTTP status code.

Limits

• The OpenAPI spec must be 10 MB or less.
• Individual API responses are truncated at 1 MB.

Example

See the full Pet Store example for a working agent configuration.