Publish API docs and an MCP endpoint from one spec with a custom domain

Most teams publish documentation the hard way: the spec lives in one repo, the docs site in another, the mock server in a third, and when an MCP endpoint appears in 2026 it gets a fourth. Every release is a four-way synchronization that fails silently, and the partner integrating against stale docs is the one who finds out. It does not have to be structured like that. One OpenAPI document can publish to two audiences — humans reading docs, agents calling MCP tools — from a single action, on a domain you control.

What one publish action should produce

Given a versioned OpenAPI 3.2 document, the target state is:

• Reference docs at https://api.yourcompany.com/docs, server-rendered, with try-it pointed at a sandbox.
• An MCP endpoint at https://api.yourcompany.com/mcp, speaking the MCP protocol over HTTP, exposing the same operations as tools.
• Versioning so v1 stays live while v2 is previewed, with each version pinned to an immutable spec revision.
• Access control — public docs for the external surface, token-gated docs and tools for internal or partner-only operations.
• One rollback, because both artifacts came from the same revision.

The key word is revision. If docs and MCP are generated from the same immutable artifact, "the docs say X but the server rejects X" becomes impossible by construction rather than by discipline.

The layout that works on a custom domain

You do not need a separate domain for docs. Subpaths on the API or marketing domain inherit its authority for search and keep cookies and CSP sane:

In front: a CDN (CloudFront, Cloudflare, Fastly) serving the static docs and proxying the dynamic paths to the runtime. On the origin, the docs are a static build from the spec; the MCP endpoint is a thin stateless adapter — the same generated mapping described in turning an OpenAPI spec into an MCP server: operation to tool, schemas to inputSchema, upstream calls with the caller's token.

Powerduck Cloud is the hosted version of exactly this layout: publish a document and it provisions the docs view and the MCP endpoint under your workspace, with custom-domain support so the URLs stay on yourcompany.com; the self-hosted/desktop side keeps the same workflow entirely local for teams who do not want a platform in the loop.

Access control: three audiences, one document

The spec describes the whole API; not every reader should see all of it. The model that holds up:

1. Public operations carry a tag or extension marking them external; the public docs build filters on it.
2. Partner operations require a scoped token; the docs and the MCP endpoint both check it, and partners see only the operations their token allows.
3. Internal operations never publish to the external deployment at all — the CI job builds an internal variant from the same source document with a different filter and deploys it to an internal distribution.

For MCP specifically, issue tokens per integration rather than sharing one account key: a partner's agent gets a token scoped to their operations with a TTL, and revoking an integration means revoking one token, not rotating credentials embedded in twenty clients.

Versioning without a folder of copies

Two versioning mistakes dominate. The first is encoding versions in paths inside the docs (/docs/v2/reference/...), which fragments search ranking and breaks every saved link on a major release. The second is silently updating "the docs" so readers cannot tell which deployed API they describe.

The working pattern:

• URLs stay versionless (/docs/reference/create-project); a version switcher selects the revision.
• Each publish creates an immutable revision with an identifier; latest, stable, and next are pointers at revisions.
• The MCP endpoint takes an optional version header or path (/mcp/v1), defaulting to stable, so agent integrations pin deliberately instead of inheriting breaking changes.
• Deprecation renders in the docs (deprecated: true plus the sunset note from the spec) and as a tool description warning for agents — both audiences get the migration message from the same field.

The CI pipeline

A boring pipeline is the goal:

1. Spec PR merges; CI validates the document against OpenAPI 3.2 and runs contract tests (the scenario suite against staging — see scenario testing from OpenAPI).
2. The build renders static docs and builds the MCP adapter image from the same spec artifact, tagged with the revision id.
3. A staging deployment serves both at internal URLs for review.
4. Promotion moves the stable pointer; CDN invalidation covers docs, the MCP runtime rolls with zero downtime because old revisions stay available.
5. Rollback repoints stable at the previous revision — docs and tools move together.

If the MCP adapter is generated code committed to a repo, it drifts; if it reads the spec at runtime from the published artifact, it cannot. Prefer the runtime adapter and treat the spec as configuration.

SEO and discoverability details

For the docs half, the static build must emit per-operation pages with real titles, meta descriptions pulled from summaries, a sitemap, and code samples as text (not canvas). Host under a subpath of the main domain to inherit authority. For the MCP half there is no page to rank, but there is an equivalent of discoverability: ship a machine-readable manifest at /.well-known/ or document the endpoint URL and scopes in the docs so internal onboarding is one copy-paste into the agent client's config.

The smallest useful first step

Do not build the four-path platform on day one. Publish one spec — the one partners ask about most — to hosted docs plus an MCP endpoint on a developer. subdomain, with one partner token and two revisions (stable and next). Run it for a month. The questions that actually matter (how partners want scopes, which operations agents misuse, how version deprecations land) only appear once something is live.

The Cloud overview shows the hosted publishing tiers and the demo opens the publish flow on a sample document; the local-first side of the same workflow is covered in publishing API docs should not require a docs project.

What to read next: one spec, two audiences: humans and AI agents and the MCP server is a build artifact cover the two sides of this pipeline in more depth.