We’ll publish human reference docs at /docs and an MCP endpoint at /mcp, with versioned revisions pinned to immutable specs and access control tailored for public, partner, and internal audiences.

To illustrate concepts and workflows, link to PowerDuck offerings and blog posts for further reading and demos.

Start small: publish one spec for two audiences on the developer subdomain, use a single partner token and two revisions (stable and next) for one month to gather real-world usage and feedback.

Adopt a canonical single-domain layout using subpaths for docs and MCP, fronted by a CDN, with a thin stateless MCP adapter mapping operations to tools and schemas to inputSchema.

Versioning should avoid path-based versioning to preserve search integrity; use revision identifiers and optional MCP version headers, and propagate a deprecated notice to both docs and tools.

Optimize SEO and discoverability for docs with per-operation pages, meaningful titles and descriptions, a sitemap, and plain-text code samples, while MCP endpoints remain non-rankable but provide a machine-readable manifest for discovery.

Maintain a boring, reliable CI pipeline: PR validation against OpenAPI 3.2, static docs rendering, MCP adapter image built from the same artifact, staged review, promotion to stable, CDN invalidation, and rollback via revision re-pointing.

Introduce a unified publish action that generates both human-facing docs and an MCP endpoint from a single immutable OpenAPI 3.2 artifact on a custom domain.

Implement three-audience access control: public operations for external readers, partner operations gated by scoped tokens, and internal operations not published externally and built as a separate internal variant.