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.
Given a versioned OpenAPI 3.2 document, the target state is:
https://api.yourcompany.com/docs, server-rendered, with try-it pointed at a sandbox. https://api.yourcompany.com/mcp, speaking the MCP protocol over HTTP, exposing the same operations as tools.v1 stays live while v2 is previewed, with each version pinned to an immutable spec 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.
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:
| Path | Content | Cache |
|---|---|---|
/docs |
Rendered reference + guides (static HTML) | CDN cached |
/docs/assets/* |
Renderer assets | Long-lived, hashed |
/mcp |
MCP HTTP endpoint (tools/list, tools/call) | Never cached |
/mock (optional) |
Sandbox proxy for try-it | Never cached |
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.
The spec describes the whole API; not every reader should see all of it. The model that holds up:
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.
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:
/docs/reference/create-project); a version switcher selects the revision. latest, stable, and next are pointers at revisions./mcp/v1), defaulting to 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.
A boring pipeline is the goal:
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.
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.
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.