MCP integration

Artifact Publisher is built to be driven by an agent. Connect an MCP client to your workspace and call the small lifecycle-shaped tool surface that publishes, updates, retrieves feedback, replies, lists, revokes, and configures.

Why MCP first

The agent already has the deliverable: it generated the HTML, knows what changed between drafts, and can act on feedback. MCP lets it turn that finished document into a share link without a copy-paste handoff through a separate UI.

Connect Claude Code

Start at Your workspace. After you sign in and create your personal workspace, Artifact Publisher mints a scoped publisher key once and presents a ready-to-run Claude Code command with that new key already inserted in the Authorization: Bearer header. Select Copy setup command and run it in a trusted terminal where Claude Code runs.

That command contains a secret. Claude Code stores it in local configuration, and your shell may retain it in terminal history after you paste it. Use it only on a trusted machine and remove the history entry if your shell records it. The key and command disappear from the account page after refresh or dismissal, but copies may remain in your clipboard, terminal history, and Claude Code configuration. Artifact Publisher stores only a key hash; create a replacement key if you lose it. Never paste the command or key into a prompt, source file, repository, or artifact.

Self-serve onboarding is available only on deployments where accounts have been activated. An inactive deployment says so on the account page. Other MCP clients use the same endpoint and bearer header, but their configuration shape may differ; the account page keeps a variable-reference example as an advanced/manual alternative.

Recipients still need no account. Artifact Publisher presents the plaintext key only during the one-time setup handoff; the publisher’s own clipboard, terminal history, Claude Code configuration, or secret manager may retain copies.

Scoped bearer publisher keys

The key is scoped to Artifact Publisher’s artifact lifecycle capabilities — not a login to your agent, source control, filesystem, or chat history. Publishers and agents must authenticate; reviewers never do.

• Standard Claude Code setup stores it in local MCP configuration. Advanced/manual setups may keep it in an environment variable or secret manager instead.
• Never commit it or embed it in an agent prompt; send it only as the bearer credential on the MCP connection.
• Treat possession as authorisation. Rotate a key when it is exposed.
• Never include it in an artifact: artifact content is visible to every holder of the share link.

Keys carry explicit scopes, and each tool declares the one it needs:

Scope	Tools
artifacts:read	list_artifacts, get_artifact_state, get_artifact_board (deprecated)
artifacts:write	publish_artifact, update_artifact, revoke_artifact, set_artifact_state, reset_artifact_state, reset_artifact_board (deprecated)
feedback:read	get_feedback
feedback:write	reply_to_feedback
workspace:configure	configure_workspace

workspace:configure is deliberately separate, so a publish-only agent key cannot change workspace defaults.

This integration uses scoped bearer API keys. It does not claim OAuth, identity-based client authorisation, or a particular account/session model.

The tools

The server advertises the authoritative schemas through MCP tool discovery. This table describes the lifecycle conceptually.

Tool	Purpose	Result
publish_artifact	Turn a title and finished self-contained HTML into a shareable artifact.	Artifact identifier and stable unlisted link
update_artifact	Publish a revision without replacing the link the recipient holds.	New immutable version behind the same link
get_feedback	Read optional recipient comments as structured data.	Page-level comments with their version
reply_to_feedback	Answer a recipient comment in its thread.	Reply attached to that comment
list_artifacts	See artifacts available to the current workspace credentials.	Artifact states and current versions
revoke_artifact	Stop serving an artifact to holders of its link.	Confirmation that the link no longer resolves to content
get_artifact_state	Read the artifact’s shared JSON state document.	Snapshot { revision, values, resetAt }
set_artifact_state	Atomically set supplied top-level keys; other keys survive.	Updated snapshot
reset_artifact_state	Clear the entire shared document (publisher only).	Empty snapshot with bumped revision
get_artifact_board	Deprecated: board projection of the same document. Prefer get_artifact_state.	Board-shaped items snapshot
reset_artifact_board	Deprecated: clears the entire shared document. Prefer reset_artifact_state.	Empty snapshot
configure_workspace	Read or change the workspace defaults a publisher may set.	Current settings plus the platform limits you cannot change

What a client may configure — and what it may not

Configurable per link, on publish_artifact:

• title
• expires_at
• comments_enabled

Configurable per workspace, on configure_workspace:

• comments_enabled — a ceiling, not a default. A link cannot enable comments in a workspace that has them off.
• default_expiry_seconds
• default_artifact_title

Not configurable by any client. These are platform guardrails, and naming one in a settings patch is rejected with the offending keys listed:

Guardrail	Why it is fixed
max_artifact_bytes	The 10 MiB ceiling bounds storage and transfer cost for every workspace.
rate_limits	Protects the anonymous comment endpoint and publisher writes from abuse.
isolation / origins	The two-origin split is the security model; it is not a preference.
storage_key_prefix	Object keys encode workspace, artifact, and version, which is what makes versions immutable.
security_headers / content_security_policy	Sandboxing and CSP are what contain untrusted artifact HTML.
visibility	v1 has no public listing surface, so a link cannot be widened.

A rejection names the guardrail rather than silently dropping the field. Silently ignoring max_artifact_bytes would let an agent believe the ceiling had been raised.

Publish, share, then optionally review

1. Call publish_artifact with self-contained HTML and receive the stable link.
2. Give the link to the recipient. They open the artifact in a browser without your agent or tooling.
3. If the recipient comments, call get_feedback and optionally reply_to_feedback.
4. Publish an immutable revision behind the stable link, or revoke when the work should no longer be reachable.

Feedback is optional and pull-based: retrieve it with get_feedback. No push notification or webhook capability is claimed.

Guidance for agent authors

• Publish HTML with one tool call from the orchestrating agent. Write the document to disk, load it, and call publish_artifact / update_artifact once with the full html string. Do not hand the invoke to a long-running subagent that re-discovers tools or probes Shell when a call fails — large documents are awkward to embed in nested tool loops. On a validation error, read the tool error text (it names the missing fields); do not assume the tool schema changed.

• Shared interactive state lives on the control plane. HTML authors use the injected ArtifactRelayState helper on the review link (or deprecated ArtifactRelayBoard for checklists). Do not invent fetch calls from the sandbox.

• Publish self-contained HTML. Inline the markup, styling, and resources needed to render the deliverable. The artifact sandbox blocks all network access, so external assets will not load.

• Update instead of making a second link. Use update_artifact when revising work a recipient is already reviewing.

• Read feedback with its version. A comment describes the version it was left on; preserve that association as the document changes.

• Keep secrets out of artifacts. Link holders can read what the artifact contains.

• Revoke intentionally. Revocation ends future service of the link, not copies a recipient already has.

Current limits

• Artifacts are one self-contained HTML document, up to 10 MiB of UTF-8
• Feedback is page-level, not DOM- or line-anchored
• Share links are unlisted possession links, not per-recipient access control
• External assets and network-dependent documents are not supported
• No compliance certification, audit, or attestation is claimed