Need MCP Documentation in Existing Portal Pipelines
Enterprises with mature OpenAPI portal pipelines need MCP-server documentation that flows through the same build process — not vendor-coupled extensions or a parallel doc system.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Maya, the developer experience and AI engineering lead, runs an internal API portal — a custom Swagger-UI client backed by a legacy database that gets populated automatically when the build process deploys OpenAPI files. Now MCP servers are showing up on the same developer surface, and she needs them to flow through the same pipeline. Vendor-driven OpenAPI extensions like Zuplo
x-mcp and Redocly x-mcp look promising, but they couple her MCP documentation to a specific portal vendor’s Redoc fork — which doesn’t fit her in-house renderer or her vendor-neutral build pipeline. She doesn’t need a new portal; she needs MCP docs that drop into the one she has.
Problem Context
- Mature enterprises already have a build → DB → portal pipeline that publishes OpenAPI today: “we have our own internal thing.. uses a custom swagger ui client to display docs”, “a big legacy thing backed by a database that is populated by a build process when we deploy all of our oas files”
- Emerging answers are vendor-driven OpenAPI extensions: Zuplo
x-mcp, Redoclyx-mcp— both extend OpenAPI rather than offer an open spec - Vendors with Redoc-based portals can adopt their own extensions cheaply; everyone else gets vendor-coupled docs that don’t render in their existing client
- The actual goal is portal-rendering, not yet-another-spec: “looking for a way to expose the mcp docs into a portal”
Problem Impact
- MCP docs end up in a parallel system from REST docs, creating two surfaces for the same developers to maintain
- Build / CI pipelines either bypass MCP entirely or invent ad-hoc emit steps that diverge across teams
- Adopting a vendor extension creates lock-in to that vendor’s portal stack — and a migration cost when MCP doc standards converge
- Without a vendor-neutral path, MCP documentation lags MCP server deployment, mirroring the gap that already exists between MCP servers and their human-readable docs
Naftiko Today
- YAML capability specs are vendor-neutral and self-contained — the same artifact carries
consumes:(the upstream API) andexposes:(REST + MCP), so one source of truth feeds whatever portal renderer the team already uses - REST API exposure with full HTTP semantics renders today in any Swagger-UI / Redoc / custom OpenAPI client without modification
- Agent Skills exposure auto-generates HTTP APIs for skill discovery, providing a machine-readable MCP catalog endpoint that fits existing build → DB → portal patterns
- JSON Schema validation ensures every capability spec is structurally complete, so a build process can fail loudly on malformed MCP docs the same way it fails on malformed OpenAPI
Naftiko Tomorrow
- OpenAPI-to-Naftiko import (Second Alpha) lets enterprises lift their existing OAS catalog into Naftiko capabilities without re-authoring, so the same build pipeline keeps working
- Naftiko Shipyard MVP (Fleet Second Alpha) provides a build-time emit step that produces both OpenAPI and MCP catalog artifacts from one capability YAML, dropping into existing CI pipelines
- TechDocs integration (Fleet First Beta) auto-publishes capability documentation into the organization’s developer portal, including custom Swagger-UI clients that already speak OpenAPI
- JSON Schema Store publication (GA) makes the capability YAML schema public and tooling-agnostic, so any portal vendor — not just Zuplo or Redocly — can render Naftiko-described MCP servers without coupling