Return Links, Not HTML: MCP Tool Results for Generated Artifacts

Table of contents

1. Why raw HTML is the wrong tool result
2. What the publishing result should include
3. How to shape the agent handoff
4. When to use the API instead
5. The practical takeaway

Why raw HTML is the wrong tool result

Generated HTML can be long, visually dense, and full of details that are easier to review in a browser than inside an agent transcript. If an MCP tool returns the whole document as text, the user gets a noisy conversation and the next agent gets a large blob to parse before it can do anything useful.

The Model Context Protocol already gives tool authors better shapes for responses. Tool results can include content, structuredContent, resource links, and output schemas. OpenAI's Apps SDK also distinguishes between visible result content, structured content, and _meta that can hydrate a UI without exposing everything to the model.

For BinHTML, that points to a simple rule: publish the HTML first, then return the link and the metadata that make the link useful.

What the publishing result should include

A good publishing result should be small enough for the agent to keep in context and explicit enough for a human to trust. For a single artifact, the useful fields are usually:

• url: the share URL the user should open.
• managementUrl: the place to review visibility, expiry, source access, and revocation.
• title: the artifact name the agent used when publishing.
• sourceAvailable: whether reviewers can inspect the submitted HTML source.
• visibility: whether the link is private, unlisted, or public in the product's terms.
• expiresAt: the expiry timestamp when one is set.
• nextAction: a short sentence the agent can show to the user.

For a multi-artifact run, the same pattern applies at the project level. The tool should return one project share URL plus a short list of included artifacts. That makes a design review, research packet, or generated report set easier to pass around than a list of unrelated links.

BinHTML's MCP docs are built around that agent-facing flow. The agent creates or selects the artifact, calls the publishing tool, and returns the published BinHTML URL. The API docs cover the same publishing concept for scripts and CI jobs.

How to shape the agent handoff

The best handoff is not just a URL. It is a compact review packet that tells the next person what happened and where to continue.

Use this pattern in the agent's final message after publishing:

• Start with the BinHTML link.
• Say what the artifact represents.
• Mention whether source access is available.
• Point reviewers to compare when the artifact is a revision or variant.
• Call out expiry or revocation if the link is temporary.

This keeps the transcript useful even after the artifact leaves the agent session. A teammate can open the link, inspect the rendered HTML, compare it with another version, and decide whether to keep sharing it.

It also helps future agents. If the next agent sees a stable URL and structured metadata, it can summarize the handoff or publish a revised version without re-reading a full HTML file from chat history.

When to use the API instead

MCP is useful when an agent should discover and call a publishing tool as part of a conversation. It is a good fit for Claude Code, Codex, Cursor-style agents, and internal assistants that already use tool servers.

The REST API is better when the workflow is deterministic. A CI job, nightly report generator, or internal dashboard exporter usually knows exactly when to publish and what fields to send. In that case, a direct HTTP call is simpler to test, log, and retry.

The output contract should still be the same. Whether the artifact came from MCP or the API, return a link, metadata, and review instructions. That consistency is what makes generated HTML portable across agents, scripts, and human review workflows.

The practical takeaway

Treat generated HTML as an artifact, not as transcript text. Publish it to a controlled viewer, return a small structured result, and hand reviewers a link they can open, compare, revoke, or revisit.

That is the difference between an agent that merely produces HTML and an agent that completes the review handoff.