Two new OpenAPI extensions hit the developer portal market this year.
Zuplo shipped x-mcp. Redocly shipped x-mcp. They look almost identical because they are solving the same problem from the same angle: extending OpenAPI to describe MCP server tools so the same documentation pipeline that publishes REST API docs can also publish MCP server docs.
This is good for the vendors. They get to say “MCP support” in their feature list. It is good for customers who already use Zuplo or Redocly — they get a marginal extension to a tool they already pay for.
It is not good for the rest of us.
Last week I had a Slack DM with an engineering lead at a Fortune-50 enterprise. He asked whether there was a spec for documenting MCP servers analogous to OpenAPI. I sent him to the Naftiko Framework. He came back with both x-mcp extension links and a working description of his portal: a custom Swagger-UI client backed by a legacy database that gets populated by a build process whenever they deploy OpenAPI files.
His problem was not “does an extension exist?” — there are now two. His problem was “how do I get MCP docs into the build pipeline I already have?” Neither vendor extension answered that. Both required adopting either Zuplo or Redocly’s renderer. Neither rendered in his existing in-house Swagger UI client. Neither traveled cleanly through his build → DB pipeline.
Vendor extensions are an upgrade path, not a portability path. They lock the documentation surface to the vendor that ships them.
What capability YAML does instead
A Naftiko capability YAML carries the same information x-mcp extensions try to carry — and more — without coupling to any portal vendor.
In one self-contained artifact, a capability YAML declares:
consumes:— the upstream API operation, with full HTTP semantics, auth, parametersexposes:— REST and MCP and Agent Skills surfaces over the same operation- typed inputs and outputs — JSONPath mappings that reshape the upstream payload into task-ready context
- governance metadata — Spectral rules, policy tags, sensitivity classifications
- identity bindings — who the agent runs as when it calls the operation
The same artifact ships into your Naftiko Engine, into your Backstage catalog, into your build pipeline as an OpenAPI emit, and into your MCP catalog. One source of truth, many rendering targets, no vendor coupling.
If you already render OpenAPI in a custom Swagger UI client, your Naftiko-shaped capability YAML emits valid OpenAPI as a build artifact. It renders unchanged. The MCP half is a sibling artifact your portal can render alongside it without picking a vendor’s Redoc fork.
The integration platform argument
The other thing vendor extensions miss is the integration platform layer.
Zuplo and Redocly are documentation portals. They do not run your capabilities. They do not enforce your governance rules at runtime. They do not capture the metrics from your agents calling your APIs. The x-mcp extension is documentation only — it tells a reader what an MCP server should look like, not what one does.
Capability YAML is the runtime artifact. The Naftiko Framework reads it, executes the upstream call, exposes the MCP tool, captures the metrics, applies the governance gates, and emits the audit trail. Documentation is one of many things the artifact produces — it is not the only thing, and it is not the primary thing.
That distinction matters more in 2026 than it did in 2024. MCP traffic is moving from prototype to production. The artifacts that describe MCP servers need to do more than render in a portal. They need to run.
Three dimensions
Technology: capability YAML is open, vendor-neutral, and rendering-pipeline-agnostic. It emits valid OpenAPI for any portal that already speaks OpenAPI. It also emits MCP catalogs without an extension fork.
Business: the cost of MCP adoption is not the protocol — it is the integration cost of getting MCP into pipelines you already have. Capability YAML lowers that cost by speaking the format you already render.
Politics: vendor extensions are governance off-ramps. Once your MCP docs live in x-mcp, your portal vendor effectively owns the spec for MCP at your company. Capability YAML keeps the spec in your repo, in your build pipeline, in your governance rules.
What to do about it
If you are using Zuplo or Redocly today, x-mcp works. Use it where it fits.
If you are running a custom developer portal — or planning to publish MCP through any pipeline that is not coupled to one of those two vendors — capability YAML is the path that does not lock you in. It travels through whatever build process you already have. It feeds whatever portal you already render. It runs the capability whether the portal is up or not.
If the registry is the catalog and the capability is the contract, the contract is the thing that travels.
