Skip to main content

mcp-openapi client

mcp-openapi client

The mcp-openapi client binding parses OpenAPI specifications from a catalog and compiles routed operations — named individually or bulk-selected by spec, tag, or glob pattern — into a generated composite mcp-http proxy binding, exposing them as MCP tools and resources with a single spec parse.

mcp_openapi_client:
  type: mcp-openapi
  kind: client
  options:
    specs:
      github:
        catalog:
          my_catalog:
            subject: github
            version: latest
        security:
          bearerAuth: my_guard
    tools:
      create_pr:
        description: Create a pull request to merge one branch into another.
  routes:
    - when:
        - tool: create_pr
      with:
        spec: github
        operation: create_pr
    - when:
        - resource: read_order
      with:
        spec: github
        operation: read_order
    - with:
        spec: github
        tag: issues

Configuration (* required)

options

object

The mcp-openapi specific options.

options:
  authorization:
    my_guard:
      credentials:
        headers:
          authorization: Bearer {credentials}
  specs:
    github:
      server: https://api.github.com
      catalog:
        my_catalog:
          subject: github
          version: latest
      overlay:
        my_catalog:
          subject: github-overlay
          version: latest
      security:
        bearerAuth: my_guard
  tools:
    create_pr:
      title: Create Pull Request
      description: Create a pull request to merge one branch into another.
      summary: "Created pull request #${result.number}"
      input:
        model: json
        catalog:
          my_catalog:
            - subject: create_pr_input
              version: latest
      output:
        model: json
        catalog:
          my_catalog:
            - subject: create_pr_result
              version: latest
  resources:
    read_order:
      description: Read a customer order by id.
      mimeType: application/json

options.authorization

object as map of named object

Guard credentials to inject into every upstream http request generated by this binding. At most one guard may be referenced.

authorization.credentials

object

Credentials derived from the named guard.

credentials.headers

object as map of named string

HTTP request headers added to the upstream request, with values resolved from the guarded session.

  • {credentials} Replaced with the raw credentials presented to the named guard.
  • {identity} Replaced with the authorized identity resolved by the named guard.

options.specs

object as map of named object

OpenAPI specifications available to routed operations. The named key is the spec label referenced by a route's with.spec.

specs.server

string

Overrides the server URL declared by the OpenAPI specification, used to resolve the :scheme, :authority, and base path of the generated upstream http request.

specs.catalog

object as map of named object

Catalog reference resolving the OpenAPI document. The named key references a catalog defined elsewhere in the configuration.

catalog.subject*

string

Subject name identifying the OpenAPI document in the named catalog.

catalog.version

string | Default: latest

Specific version of the registered OpenAPI document.

specs.overlay

object as map of named object

Catalog reference resolving an OpenAPI Overlay document, applied to the OpenAPI document before it is parsed. Overlay actions can patch or extend the base document — for example, to add a security requirement or servers entry — without duplicating it. Uses the same shape as specs.catalog.

The `x-zilla-mcp` operation extension

An OpenAPI operation — whether authored directly in the base document or added by an overlay action — may carry an x-zilla-mcp object to supply MCP-specific metadata without an authored options.tools override:

paths:
  /pulls:
    post:
      operationId: create_pr
      x-zilla-mcp:
        title: Create Pull Request
        description: Open a pull request from one branch into another.
        annotations:
          readOnlyHint: false
          destructiveHint: false
          idempotentHint: false

tools.title, tools.description, and each tools.annotations hint fall back to this extension before falling back further still. This is how mcp-kafka-connect and mcp-schema-registry supply real tool titles, descriptions, and annotations for their bundled specs via an overlay, without editing the vendored OpenAPI document itself.

specs.security

object as map of named string

Maps each OpenAPI securityScheme name declared by the specification to the named guard that authorizes it. Resolution is best-effort: a security requirement naming a scheme absent from this map is simply not enforced, rather than rejecting the operation. A route is only rejected outright when the operation declares multiple OR-alternative security requirements, or when a single alternative requires more than one distinct guard at once — Zilla routes can reference only one guard.

options.tools

object as map of named object

Overrides for MCP tools generated from routed OpenAPI operations. The named key is the tool name — either an explicit route's when[].tool, or the automatic name assigned to a bulk-selected operation (see routes).

tools.title

string

Tool title surfaced to MCP clients by tools/list, overriding the operation's x-zilla-mcp.title vendor extension (see above). OpenAPI operations have no native title field, so a tool without either an override or the extension has no title.

tools.description

string

Tool description surfaced to MCP clients by tools/list, overriding — in order — the operation's x-zilla-mcp.description vendor extension (see above), its own native description, and finally its operation id.

tools.summary

string

Result summary template surfaced as the tool-call text result, overriding the OpenAPI operation's own summary, which is itself the fallback before a generic literal naming the operation. Supports ${result.x} interpolation, where x references a property of the upstream JSON response.

tools.input

object

Model overriding the schema generated from the OpenAPI operation's parameters and request body, used to validate the tools/call arguments before the upstream http request is dispatched.

input:
  model: json
  catalog:
    my_catalog:
      - subject: create_pr_input
        version: latest

input.model*

string

Model name used to convert and validate the value, such as json.

input.catalog

object as map of named array

Catalog subjects resolving the schema used for validation.

catalog[].subject*

string

Subject name identifying the schema in the named catalog.

catalog[].version

string | Default: latest

Specific version of the registered schema.

tools.output

object

Model overriding the schema generated from the OpenAPI operation's success response, surfaced as the tool-call structuredContent. Uses the same shape as tools.input.

tools.annotations

object

Behavior hints surfaced to MCP clients by tools/list, overriding the operation's x-zilla-mcp.annotations vendor extension (see above), itself the fallback before an HTTP-method-derived default. Each hint resolves independently — overriding one does not require overriding the others.

annotations:
  readOnlyHint: false
  destructiveHint: false
  idempotentHint: false

annotations.readOnlyHint

boolean

Whether the tool only reads data without modifying any state. Defaults to true for a GET or HEAD operation, otherwise unset.

annotations.destructiveHint

boolean

Whether the tool may perform a destructive update. Defaults to true for a DELETE operation, otherwise unset.

annotations.idempotentHint

boolean

Whether calling the tool repeatedly with the same arguments has no additional effect beyond the first call. Defaults to true for a PUT or DELETE operation, otherwise unset.

annotations.openWorldHint

boolean | Default: false

Whether the tool interacts with an open-ended set of external entities, rather than a fixed, closed set. Always defaults to false unless overridden or supplied by the x-zilla-mcp extension.

options.resources

object as map of named object

Overrides for MCP resources generated from routed OpenAPI operations. The named key is the resource identifier used by a route's when[].resource — not the URI ultimately surfaced by resources/list, which is derived from the OpenAPI path.

resources.description

string

Resource description surfaced to MCP clients by resources/list. Unlike tools.description, there is no fallback to the OpenAPI operation's own description or its operation id — a resource with no authored override here has no description.

resources.mimeType

string

MIME type of the resource contents surfaced to MCP clients, overriding the MIME type derived from the OpenAPI operation's success response content.

resources.output

object

Model overriding the schema generated from the OpenAPI operation's success response, surfaced as the resource contents. Uses the same shape as tools.input.

routes*

array of object

Conditional mcp-openapi specific routes, compiling matched OpenAPI operations into the generated mcp-http proxy as MCP tools or resources. At least one route is required.

A route either names a single operation explicitly, or bulk-selects many operations at once:

  • Explicit — with.operation names one exact operationId. May pair with when[].tool or when[].resource to name and shape the generated MCP primitive.
  • Bulk — with.spec alone selects every operation in the spec, with.tag selects every operation carrying the named OpenAPI tag, or with.operation containing a * selects every operation whose id matches the glob pattern. Bulk-selected operations always become tools, never resources, and cannot be named with when[].tool or when[].resource — each is named automatically.
routes:
  - when:
      - tool: create_pr
    with:
      spec: github
      operation: create_pr
  - with:
      spec: github
      tag: issues
  - with:
      spec: github
      operation: "search_*"

Route precedence and default tool naming

Routes are evaluated in order, and the first route to claim an operation removes it from consideration by every later route. A bulk-selected operation not given an explicit name is named after its operationId converted to snake_case, falling back to a slug of its method and path when the id is absent or already taken, then a numeric suffix on any further collision.

routes[].guarded

object as map of named array of string

Additional roles required by the named guard, independent of any guard already resolved from the OpenAPI operation's own security requirement (see specs.security). Roles for the same guard are unioned into one entry; roles naming a different guard add a separate entry that must also authorize.

routes:
  - guarded:
      my_guard:
        - pr:write

routes[].when

array of object

List of conditions (any match) to name or filter the tool or resource generated for the matched route. Read more: When a route matches

routes:
  - when:
      - tool: create_pr
      - resource: read_order

when[].tool

string

Tool name surfaced to MCP clients by tools/list and matched by tools/call, naming the explicit OpenAPI operation routed by with.operation. Not allowed on a bulk route.

when[].resource

string

Resource identifier matched by resources/read, naming the explicit OpenAPI operation routed by with.operation. Not allowed on a bulk route.

Resource vs. resource template

An operation whose OpenAPI path contains a {param} capture is surfaced as a resource template through resources/templates/list. Otherwise it is a concrete resource surfaced through resources/list, with any query parameters appended to its URI as an RFC 6570 {?name1,name2} suffix rather than disqualifying it from being concrete.

routes[].with*

object

Resolves the OpenAPI operation or operations compiled into the generated mcp-http proxy for this route.

with:
  spec: github
  operation: create_pr

with.spec*

string

Spec label to route to, referencing an entry in options.specs.

with.operation

string

Exact OpenAPI operationId to route, or a * glob pattern matching many operation ids in bulk, within the named spec. Cannot be combined with tag.

with.tag

string

OpenAPI tag to bulk-select every operation carrying it, within the named spec. Cannot be combined with operation.

with.params

object as map of named string

Rebinds an OpenAPI path, query, header, or cookie parameter to a different expression than its default ${args.name} (tool) or ${params.name} (resource) passthrough. The named key is the OpenAPI parameter name; the value is the replacement expression, with or without the surrounding ${ }. Applies to every operation matched by the route, so it works the same on a bulk route as on an explicit one.

with:
  spec: github
  operation: create_pr
  params:
    owner: ${args.repository.owner}
    repo: ${args.repository.name}

with.body

object as map of named string

Explicit upstream request body, mapping each body property to an interpolated value, in place of the schema generated from the OpenAPI operation's request body. Supports ${args.x} interpolation, where x references a property of the tools/call arguments. Use a template to rename or restructure arguments before dispatch.

with:
  spec: github
  operation: create_pr
  body:
    title: ${args.title}
    head: ${args.pr.branch}
    base: ${args.pr.target}

telemetry

object

Defines the desired telemetry for the binding.

telemetry.metrics

array

Telemetry metrics to track

telemetry:
  metrics:
    - stream.*

telemetry.attributes

object as map of named string properties

Telemetry attributes to add to the binding metrics.

Gateway Version