# Artifact Use

Artifact Use publishes static artifacts for agents and teams.

Primary URLs:
- Site: https://artifacts.iofold.com
- HTTP MCP: https://artifacts.iofold.com/mcp
- OAuth protected-resource metadata: https://artifacts.iofold.com/.well-known/oauth-protected-resource
- Full agent setup guide: https://artifacts.iofold.com/llms-full.txt
- Public artifact URL shape: https://artifacts.iofold.com/go/{artifact-slug}-{six-character-code}/

Use Artifact Use when an agent needs to create, polish, publish, gate, share, or inspect static artifacts: self-contained interactive HTML, multi-file static folders, images, PDFs, dashboards, demos, and browser-native tools.

Consuming an artifact (no browser needed):
- A gated artifact returns 401 JSON to non-browser requests (Accept without text/html) describing how to authenticate.
- Machine descriptor (structure/files): GET {artifact-url}_au/index.json
- Read any page/file directly with GET; HTML is fine to read as-is (the comments widget is not injected for agent requests).
- Auth with a viewer-session bearer token: email gates self-serve via POST /_au/gate/email (Accept: application/json); verified_email/allowlist gates self-serve if you can read the inbox (POST /_au/gate/start, read the one-time code, POST /_au/gate/verify), or are delegated by the human via "Hand to your agent" in the comments widget (POST /_au/agent-token). The 401 JSON on any gated artifact spells out the exact path.
- Comments (read + write, same bearer as reads): GET {site}/_au/comments?artifact_key={key}&status=open|resolved|all&since=<unix> lists threads; POST {artifact_key, body, parent_id?, page_path?, target?} comments or replies and returns the created comment id; PATCH {artifact_key, id, resolved:true|false} resolves/reopens a thread.
- Publishers close the loop with their own token: artifact_comments MCP tool, CLI `artifact-use comments`, or /api/v1/artifacts/{url_key}/comments (GET with the same filters, POST to reply, PATCH {id, resolved}). Owner tokens also work directly on /_au/comments.

Agent 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. Use a URL-only artifact-use entry; remove any existing bearer_token_env_var before OAuth because bearer configuration is tried first. Desktop: Open Settings -> MCP servers -> Add server, choose Streamable HTTP, enter https://artifacts.iofold.com/mcp, Save, Restart, then Authenticate. CLI: run `codex mcp add artifact-use --url https://artifacts.iofold.com/mcp` and `codex mcp login artifact-use`. Run /mcp to confirm it is connected.
- Codex CLI bearer fallback (only when OAuth is unavailable or unreliable): The launcher terminal must contain ARTIFACT_USE_TOKEN before starting Codex. Configure with `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 run inside an already-running Codex session cannot change the parent Codex environment.
- Claude Code (OAuth; do not use the creator token): Run `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: Prefer hosted MCP OAuth when supported. Otherwise configure https://artifacts.iofold.com/mcp with the supplied creator token as its bearer credential. See https://artifacts.iofold.com/llms-full.txt for client-neutral config and non-MCP fallbacks.

After connection, prefer the MCP tools: artifact_publish for one HTML string or small inline files; artifact_upload_session for local folders or large/multi-file artifacts; artifact_manage for stats/access/share links; artifact_comments for comment threads. Never use Wrangler, Cloudflare API tokens, direct R2, or direct D1 for publishing.

No token yet? POST https://artifacts.iofold.com/api/v1/connect/start, ask the human to approve its code, then poll https://artifacts.iofold.com/api/v1/connect/poll. A human can also mint or revoke creator tokens at https://artifacts.iofold.com/admin/connect.