The API is done. Scenarios pass against staging, the mock kept three teams alive during development, and coding agents are calling the contract over MCP instead of guessing field names. Then a partner asks the question that quietly turns into a quarter-long project: "Can you send us the docs, and is there an endpoint our agent can hit?"
Day 7, the final part of the the series, is about publishing without the project. Hosted documentation and a hosted MCP endpoint should be build artifacts of the spec — outputs of the file, not separate things a team maintains by hand.
Why docs projects derail
The traditional path is familiar and expensive: stand up a docs site, choose a generator, wire it to the repository, configure auth for private versions, set up hosting, assign an owner, and accept that the content starts drifting from the codebase the moment the launch sprint ends. For internal APIs this is pure overhead; for partner APIs it is also a credibility problem, because a partner integrating against stale fields blames your API, not your docs pipeline.
The alternative treats the document that already went through design, mock, test, and scan as the only input. Publishing becomes a deploy step with three decisions attached: which version, who can see it, and which surface (docs, MCP, or both).
What "publish" should produce
From the same OpenAPI file:
- Human-facing reference documentation — operations, parameters, request and response schemas, examples, the SSE and auth sections — rendered read-only, on a stable URL.
- A hosted MCP endpoint — the same operations exposed as discoverable tools for partner agents, with its own credentials and its own exposure scope.
- Versioning — a published version is a snapshot. Partners integrate against v1 while v2 is in review; nobody's agent silently picks up in-progress edits.
- Access control — public docs for the platform API, gated docs and MCP keys for the partner surface, read-only tools until the partner's use case justifies writes.
The local file stays the working copy. Experimental edits, half-finished operations, and internal notes never become external commitments by accident; only the version you publish is visible. That boundary is the whole reason to keep editing local and publishing explicit.
Expose a deliberate subset
The instinct to publish all forty-seven endpoints is wrong in both directions. Partners need twelve; internal tooling needs the rest. The hosted MCP surface should be curated the same way the public documentation is:
- Publish the read-only operations the partner use case actually requires.
- Verify one real query from an external client with a scoped key.
- Add write tools against a sandbox or staging-backed deployment first.
- Promote to production exposure only after the partner's scenario tests pass.
The spec describes what the API can do; exposure configuration decides what a given caller is allowed to do. Keeping those separate is what lets you hand an agent network access without handing it your entire internal surface.
The full loop, end to end
Stepping back, here is the whole workflow the series walked through:
| Day | Direction | Artifact |
|---|---|---|
| 1 | — | One local OpenAPI spec established as the source of truth |
| 2 | Design first | AI-drafted contract, reviewed as diffs, boring decisions settled up front |
| 3 | Spec → mock | A real HTTP mock from examples; downstream teams unblocked |
| 4 | Spec → tests | Scenario tests chaining real requests with extraction and schema assertions |
| 5 | Code → spec | AST scan of an existing codebase, honest gaps, rescan diffs |
| 6 | Spec → agent | MCP tools for coding agents; generated code verified by scenarios |
| 7 | Spec → partners | Versioned hosted docs and a scoped hosted MCP endpoint |
Two directions feed one file. Design, mock, and test push forward from the contract; the scanner pushes backward from the shipped code. The moment they disagree, the diff is the agenda for the next meeting — and that, more than any individual feature, is the point of the system.
What stays local, what gets published
Teams evaluating this workflow always ask the same question, so it is worth answering plainly:
- The spec file lives in version control on your machines. It is the source.
- AI assistance uses the provider and key you configure; prompts and patches go to your model, not to a vendor's backend.
- Code scanning runs locally. Source never uploads; an optional gap resolver sends only a single untyped handler, only when you ask.
- The mock and scenario runs execute against your local machine and your environments.
- Only the version you explicitly publish — rendered docs and the MCP tools you choose to expose — reaches hosted infrastructure.
Local-first is not an aesthetic preference here. It is what lets the workflow touch unreleased products, internal admin routes, and proprietary code without a security review every time someone opens the app.
If you take only the checklist
- Write or scan one real spec this week, even a partial one. Marked gaps are fine; silent guesses are not.
- Add examples to the ten endpoints your consumers actually call; start a mock from them.
- Convert one happy path into a chained scenario test, then add the idempotency and failure cases.
- Serve the spec to whatever coding agent you already use, read-only, and let it query schemas instead of receiving pastes.
- Publish one versioned, access-controlled docs/MCP surface for one real partner.
Everything after that is repetition.
The whole loop is what I build with Powerduck — a local-first workspace for the design, debug, test, mock, documentation, and MCP sides of this, with Cloud handling only the hosted publishing step. The ideas are bigger than the tool: one contract, two directions, every artifact derived. If the series changed one habit, let it be this — stop re-explaining your API to humans and agents who could be reading the same file.
Top comments (0)