Skip to main content

OpenAPI Overlay

OpenAPI Specs as Tools covers deriving MCP tools and resources directly from a spec you can edit. When the spec belongs to someone else, a vendored file, a third-party API, a document pulled from a public registry, editing it directly isn't an option.

The Problem

A vendored or third-party OpenAPI document rarely has the x-zilla-mcp metadata, security requirement, or servers entry a deployment needs, and patching it by hand means forking a file that's supposed to stay in sync with an upstream you don't control. Every upstream update has to be manually re-applied to the fork.

How Zilla Solves It

options.specs.<name>.overlay applies an OpenAPI Overlay document to the base spec before it's parsed, resolved from a catalog the same way the base spec is. An overlay action patches or extends the base document, adding a security requirement, a servers entry, or x-zilla-mcp metadata, without touching the vendored file itself:

specs:
  petstore:
    server: http://petstore:4002
    catalog:
      petstore_catalog:
        subject: petstore-spec
        version: latest
    overlay:
      petstore_catalog:
        subject: petstore-overlay
        version: latest

The base spec and the overlay are two independent catalog entries. Updating the vendored spec to a new version doesn't touch the overlay, and updating the overlay doesn't touch the vendored spec.

Supplying MCP Metadata Without Editing the Spec

OpenAPI has no native concept of an MCP tool title or behavior hint (readOnlyHint, destructiveHint, and so on). An operation can carry these through its own x-zilla-mcp vendor extension:

paths:
  /pets/{id}:
    delete:
      operationId: delete_pet
      x-zilla-mcp:
        title: Delete Pet
        description: Remove a pet from the store by id.
        annotations:
          destructiveHint: true
          idempotentHint: true

When the base document isn't yours to edit, an overlay action adds this same x-zilla-mcp block to the operation instead of hand-editing the vendored file. options.tools.<name>.title, description, and annotations still override the extension when both are present, whichever document it came from.

The same mechanism, bundled

mcp-kafka-connect and mcp-schema-registry use this same overlay/x-zilla-mcp mechanism internally, applied to a bundled OpenAPI document for their respective REST APIs, to supply real tool titles, descriptions, and annotations without editing the vendored spec. Neither exposes options.specs for you to configure directly.

Try It

Try the example

OpenAPI Specs as Tools walks through registering a spec in a catalog and compiling it into a tool; pairing it with an overlay catalog entry follows the same pattern shown above.