API and MCP HTML Publishing: Automate Artifact Links

Use the REST API when a script, CI job, scheduled task, or product integration should control authentication, payloads, retries, and response handling. Use remote MCP when an MCP-capable agent should call the publishing tool during a task and include the result in its response.

Both paths publish a complete HTML document. The choice is about orchestration and ownership, not a different kind of artifact. Keep the same content and review rules whichever interface starts the publish.

The request should contain the full HTML needed for the artifact to render, plus a title that will make sense to the recipient later. A vague title such as 'output' makes automated review harder; a title that names the report, audience, or decision creates useful context in the dashboard and handoff.

Keep content generation separate from publishing where possible. That makes it easier to inspect, redact, retry, and test the document before it crosses the publishing boundary.

The useful result is not just a successful HTTP status or a tool confirmation. The caller needs the URL that a reviewer can open, and the surrounding workflow should make clear what was published. Agent prompts and application code should ask for a concise handoff containing the share link and, when needed, the source or management link.

Returning raw HTML in an agent response defeats the point of artifact publishing. It increases message size, makes the review surface inconsistent, and forces the recipient to reconstruct the browser experience.

For a recurring report or an iterative prototype, update the existing artifact when the review object and audience remain the same. A stable URL means the next handoff can point to the current version without creating a new link every time.

Create a separate artifact when the audience, purpose, retention boundary, or review job changes. Stable URLs are useful only when their meaning stays stable too.

A single agent run may create a brief, a data summary, and a visual dashboard. Publishing each output separately is fine, but the reviewer needs an index. A BinHTML project can group related artifacts and provide a project-level handoff without forcing the agent to merge unrelated HTML into one document.

Keep project creation and naming deterministic. If each run makes a new project with a temporary name, the project list becomes difficult to navigate and the stable handoff benefit disappears.

An integration is complete only when the generated document reaches the reviewer in the expected form. Test authentication, the publish request, the returned URL, the rendered result, version updates, and the final message. For MCP, test that the agent is instructed to return the link rather than the document body.