# Artifact Use

Artifact Use publishes static artifacts for agents and teams: self-contained
interactive HTML, multi-file static folders, images, PDFs, dashboards, demos,
and browser-native tools. Every artifact gets one stable URL, immutable
versions, a viewer gate, comments, and stats. Agents publish through MCP, the
CLI, or the HTTP API; they never need Cloudflare credentials.

Primary URLs:

- Site: https://artifacts.iofold.com
- HTTP MCP (POST only): https://artifacts.iofold.com/mcp
- OAuth protected-resource metadata: https://artifacts.iofold.com/.well-known/oauth-protected-resource
- Full agent guide: https://artifacts.iofold.com/llms-full.txt
- Mint or renew a creator token: https://artifacts.iofold.com/admin/connect
- Public artifact URL shape: https://artifacts.iofold.com/go/{artifact-slug}-{six-character-code}/

Artifact Use never publishes unless you call a publish tool. Reading, listing,
stats, and comments change nothing. Publish only when the user asks for a link,
a share, a review, or a republish; prefer republishing the existing artifact
(pass its `url_key` as `artifact`, your last `version_id` as
`base_version_id`, and a one-line `change_note`) over creating a new one; and
hand the review link back in your final response.

Setup: identify the current harness and follow exactly one path.

- Codex desktop / CLI / IDE (OAuth default; do not use the creator token):
  these surfaces share MCP config and OAuth credentials on the same host, so
  one URL-only entry serves all of them. Remove any existing
  `bearer_token_env_var` from the `artifact-use` entry before OAuth, because a
  configured bearer token is tried first. Desktop: Settings -> MCP servers ->
  Add server, choose Streamable HTTP, enter
  `https://artifacts.iofold.com/mcp`, Save, Restart, then Authenticate. CLI:
  `codex mcp add artifact-use --url https://artifacts.iofold.com/mcp` then
  `codex mcp login artifact-use`. Run `/mcp` to confirm it is connected.
- Codex CLI bearer fallback (only when OAuth is unavailable or loops): export
  `ARTIFACT_USE_TOKEN` in the terminal before starting Codex, run
  `codex mcp add artifact-use --url https://artifacts.iofold.com/mcp --bearer-token-env-var ARTIFACT_USE_TOKEN`,
  then start or restart Codex from that terminal and run `/mcp`. An export
  inside an already-running Codex session cannot change its parent process.
- Claude Code (OAuth; do not use the creator token):
  `claude mcp add --transport http artifact-use https://artifacts.iofold.com/mcp`,
  then open `/mcp`, select `artifact-use`, and Authenticate in the browser.
- Other harnesses: use hosted MCP OAuth when the client supports it. Otherwise
  configure `https://artifacts.iofold.com/mcp` with the creator token as its
  bearer credential, or run the stdio server / CLI with `ARTIFACT_USE_TOKEN`
  exported. Client-neutral configs are in section 2 of the full guide.
- No token and no OAuth? Ask the user to open
  `https://artifacts.iofold.com/admin/connect`, copy the setup prompt, and
  paste it to you. Tokens expire after 90 days; a `401` whose `error.code` is
  `token_expired` carries a `renew_url` — ask the user to mint a new token
  there. Nothing else in the setup changes.

Tools after connection: `artifact_publish` (one HTML string or small inline
files, 2 MiB per file; `artifact` takes a slug or an existing `url_key` to
republish in place), `artifact_upload_session` (local folders and large or
multi-file artifacts), `artifact_manage` (list, stats, access, preview copy,
upstream backend, share links, versions, promote, diff, move, delete,
workspaces), and
`artifact_comments` (list with `wait: 25` to long-poll, reply, resolve,
reopen, subscribe a webhook). Tool failures return
`isError: true` with `structuredContent.error = {code, message, status}`.
Never use Wrangler, Cloudflare API tokens, direct R2, or direct D1 for
publishing.

Reading a gated artifact as an agent (no browser needed):

- The publishing workspace's own token (`au_creator_...` or MCP OAuth) reads
  a gated artifact directly — `GET`/`HEAD` of pages, assets and the
  descriptor — with no viewer session and no view recorded. Fetch the URL you
  just published with the token you already hold.
- Otherwise a gated artifact returns `401` JSON to non-browser requests
  (`Accept` without `text/html`) describing how to authenticate.
- Machine descriptor (structure and files): `GET {artifact-url}_au/index.json`.
- Read any page or file directly with `GET`; HTML is served as-is (the comments
  widget is not injected for agent requests).
- A share link (`{artifact-url}?v={link_id}`) passes the gate by itself:
  `recipient` and `open` links are served inline (cookie attached); a
  `password` link answers `401` with `link_kind: "password"` — exchange the
  passcode for a bearer with `POST /_au/gate/link` (form `artifact_key`,
  `link`, `passcode`; `Accept: application/json`) or send
  `Authorization: Basic base64("{link_id}:{passcode}")` on each request.
  Expired, revoked or exhausted links answer `410`.
- Authenticate with a viewer-session bearer token: email gates self-serve via
  `POST /_au/gate/email` (`Accept: application/json`; the address must parse
  and its domain must have MX or A records); `verified_email` and
  `allowlist` gates self-serve if you can read the inbox
  (`POST /_au/gate/start`, read the one-time code, `POST /_au/gate/verify`;
  a repeat start for the same address within 30 seconds sends no new email
  and answers `resent: false` with `retry_after`), or
  are delegated by the human via "Hand to your agent" in the comments widget
  (`POST /_au/agent-token`). The `401` JSON spells out the exact path.
- Comments with the same bearer:
  `GET /_au/comments?artifact_key={key}&status=open|resolved|all&since=<unix>&wait=<1..25>`
  lists threads (`wait` holds the request until a newer comment exists; pass
  the returned `next_since` back as `since`);
  `POST {artifact_key, body, parent_id?, page_path?, target?, client_ref?}`
  comments or replies and returns the created id;
  `PATCH {artifact_key, id, resolved}` resolves or reopens.
- Publishers close the loop with their own token: the `artifact_comments` MCP
  tool (subscribe a webhook, or list with `wait: 25` and work through
  `status: "open"`), CLI `artifact-use comments`, or
  `/api/v1/artifacts/{url_key}/comments`.

Versions: every publish is kept; the stable URL serves the current one and
each version is viewable at `{artifact url}_v/{version_id}/` by the
publishing workspace only (viewers are redirected to the current version).
Publish results carry `version_id`, `change_note`, `links` (`artifact`,
`version`, `review`) and `next`; hand `links.review` to the user and point
comment replies at `links.artifact`. On every republish pass `artifact` =
the `url_key`, `base_version_id` = your last `version_id`, and a one-line
`change_note` (at most 280 characters) saying what changed; humans read
version history by these notes. `artifact_manage` `versions` lists them,
`promote` (`version_id`) makes one current (rollback = promote an older
version), `diff` (`from_version`, `to_version`; default previous → current)
shows what changed per file. A `version_conflict` means someone published
in between — diff, merge, republish with the newer id.

Full guide: https://artifacts.iofold.com/llms-full.txt