{"slug": "publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain", "title": "Publish API docs and an MCP endpoint from one spec with a custom domain", "summary": "A developer outlined a workflow for publishing human-readable API documentation and a machine-callable MCP endpoint from a single immutable OpenAPI 3.2 revision, served under subpaths of one custom domain. The approach generates both the static docs site and a stateless MCP adapter at runtime from the same spec artifact, so docs and tools cannot drift, and it recommends per-integration scoped tokens with TTLs for MCP access. Powerduck Cloud is cited as a hosted implementation of the layout, with a self-hosted option that keeps the workflow local.", "body_md": "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.\n\nGiven a versioned OpenAPI 3.2 document, the target state is:\n\n`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.\nThe 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.\n\nYou 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:\n\n| Path | Content | Cache | \n|---|---|---|\n| `/docs` | Rendered reference + guides (static HTML) | CDN cached | \n| `/docs/assets/*` | Renderer assets | Long-lived, hashed | \n| `/mcp` | MCP HTTP endpoint (tools/list, tools/call) | Never cached | \n| `/mock` (optional) | Sandbox proxy for try-it | Never cached | \n\nIn 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](https://www.powerduck.com/blog/openapi-to-mcp-server-step-by-step/): operation to tool, schemas to `inputSchema`, upstream calls with the caller's token.\n\nPowerduck 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.\n\nThe spec describes the whole API; not every reader should see all of it. The model that holds up:\n\nFor 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.\n\nTwo 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.\n\nThe working pattern:\n\n`/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.\nA boring pipeline is the goal:\n\nIf 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.\n\nFor 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.\n\nDo 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.\n\nThe [Cloud overview](https://www.powerduck.com/pricing) shows the hosted publishing tiers and the [demo](https://www.powerduck.com/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](https://www.powerduck.com/blog/publishing-api-docs-shouldnt-require-a-docs-project/).\n\n**What to read next:** [one spec, two audiences: humans and AI agents](https://www.powerduck.com/blog/one-spec-two-audiences-humans-and-ai-agents/) and [the MCP server is a build artifact](https://www.powerduck.com/blog/mcp-server-is-a-build-artifact/) cover the two sides of this pipeline in more depth.", "url": "https://wpnews.pro/news/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain", "canonical_source": "https://dev.to/jeff_pdc/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain-gi0", "published_at": "2026-10-03 17:32:21+00:00", "updated_at": "2026-10-03 17:38:05.899228+00:00", "lang": "en", "topics": ["agent-protocols", "developer-tools", "ai-agents", "structured-data"], "entities": ["Powerduck Cloud", "OpenAPI", "MCP", "CloudFront", "Cloudflare", "Fastly"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain", "markdown": "https://wpnews.pro/news/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain.md", "text": "https://wpnews.pro/news/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain.txt", "jsonld": "https://wpnews.pro/news/publish-api-docs-and-an-mcp-endpoint-from-one-spec-with-a-custom-domain.jsonld"}}