HTTP APIs (OpenAPI)

Point the proxy at any OpenAPI 3.0 spec and it auto-generates MCP tools — one per enabled operation — with typed input schemas, jq response transforms, and config-time dry-run validation.

Configuration

upstreams:
  - name: kraken
    type: http
    tool_prefix: kraken
    base_url: https://api.kraken.com
    openapi:
      source: examples/kraken/spec.yaml   # path or URL
      refresh_interval: 5m                        # re-fetch spec periodically
    overlay:
      source: examples/kraken/overlay.yaml # optional customization

The source field accepts a local file path or a remote URL (https://). Remote specs are fetched with ETag/conditional GET to minimize bandwidth on refresh.

Tool naming

Tool names are derived from the operationId in the spec, slugified and prefixed with the upstream's tool_prefix:

operationId	tool_prefix	Tool name
`getSystemStatus`	`kraken`	`kraken__get_system_status`
`getTicker`	`kraken`	`kraken__get_ticker`
`listPets`	`pets`	`pets__list_pets`

Names can be overridden with x-mcp-tool-name in an overlay. When multiple upstreams would produce the same tool name, a numeric suffix is appended automatically.

Input schema generation

The proxy builds MCP tool input schemas from OpenAPI parameter definitions:

Path parameters, query parameters, and request body fields become tool arguments
Types, descriptions, enums, formats, and required flags are preserved
Synthetic examples are generated from example, default, enum, or format-specific patterns (e.g. date, uuid)

Response transforms

jq expressions transform API responses before they are returned to the MCP client. The default transform is . (passthrough). Set x-mcp-response-transform in an overlay to customize:

# Flatten Kraken's nested result wrapper
x-mcp-response-transform: >
  .result | to_entries[0] | {
    pair: .key,
    ask: .value.a[0],
    bid: .value.b[0],
    lastPrice: .value.c[0]
  }

Request bodies can also be transformed with x-mcp-request-transform. Error responses use x-mcp-error-transform. All transforms are compiled and dry-run validated at startup.

Non-JSON responses

Set x-mcp-response-format to handle binary or media responses:

Value	MCP content type
`json` (default)	`TextContent` with JSON string
`text`	`TextContent`
`image`	`ImageContent` (base64)
`audio`	`AudioContent` (base64)
`binary`	`ResourceContent` (base64)
`auto`	Detected from `Content-Type`

Disabling operations

Set x-mcp-enabled: false on any operation in an overlay to exclude it from tool generation entirely. This does not affect the upstream API — the operation simply won't appear as an MCP tool.

Dry-run validation

At startup the proxy generates a synthetic request for every enabled operation using example values from the spec. If any jq transform or schema mapping fails, the proxy refuses to start and logs the offending operation. This catches misconfigured overlays before they reach production.

x-mcp extensions reference

Extension	Type	Default	Purpose
`x-mcp-enabled`	bool	`true`	Include operation as a tool
`x-mcp-tool-name`	string	derived	Override generated tool name
`x-mcp-auth-required`	bool	`true`	Per-operation auth bypass
`x-mcp-safe`	bool	`false`	Mark as read-only for group filters
`x-mcp-response-format`	string	`json`	Response content type
`x-mcp-request-transform`	string	generated	jq expression for request body
`x-mcp-response-transform`	string	`.`	jq expression for response
`x-mcp-error-transform`	string	default	jq expression for error responses
`x-mcp-tier`	string	—	Arbitrary label for group filters