# Artifacto: setup guide for AI agents

You were sent here by a person who wants you connected to **Artifacto**, B-Stock's home for things agents make: self-contained HTML artifacts and markdown documents, organized in folders. Set it up for them, step by step, and keep your messages to them short.

## What you are connecting to

- **MCP server:** `https://artifacto.bstock.io/mcp` (Streamable HTTP)
- **Sign-in:** OAuth 2.1 with dynamic client registration and PKCE. Your MCP client handles it: it opens a browser tab where the person signs in with their B-Stock Google account and clicks **Approve**. There is no API key to copy.
- **Access:** you act as that person. You see only what they can see, you publish as them, and you can change or delete only items they own. Access lasts up to 30 days, then they approve again.

## Steps

Setup takes a minute or two. In Claude Code and Codex CLI it is two commands; you run them and the person clicks **Approve**.

1. **Work out which client you are running in, and check whether Artifacto is already there** (`claude mcp get artifacto`, `codex mcp get artifacto`, or the client's settings). If it is, do not add it again (a copy such as `artifacto-2` only adds confusion): go straight to its sign-in. Otherwise set it up below. If your rules say to ask before changing configuration, ask first.
   - **Claude Code:** run `claude mcp add --scope user --transport http artifacto https://artifacto.bstock.io/mcp` (always `--scope user`: the default is local to the current folder, so the server would be missing in every other project). To sign in, the person types `/mcp`, picks **artifacto** and chooses **Authenticate**.
   - **Codex CLI:** run `codex mcp add artifacto --url https://artifacto.bstock.io/mcp`, then `codex mcp login artifacto`, which opens the sign-in. If either command is missing, the person needs a newer Codex. If your sandbox cannot write `~/.codex/config.toml`, give the person the two commands to paste into their own Terminal.
   - **Claude Desktop or claude.ai:** the person adds it, and you walk them through it: Settings → Connectors → **Add custom connector**, name it Artifacto, paste `https://artifacto.bstock.io/mcp`, then **Connect**. In the desktop app the person must then **quit and reopen it** (Cmd+Q on a Mac, not just closing the window): it only loads new tools at startup. On claude.ai, a new chat is enough.
   - **ChatGPT (desktop or web):** the person adds it, and you walk them through it one step at a time. ChatGPT keeps custom MCP servers somewhere easy to miss: in a **Work** session, open **Plugins → Install plugin → Add custom MCP**, choose **OAuth** as the authentication, paste `https://artifacto.bstock.io/mcp`, then click **Install as plugin**, which opens the sign-in. Adding the server under Settings → Plugins → MCP is **not** enough: chats get no tools from it. (That setting is shared with Codex CLI on the same machine, so it does help Codex.)
   - **Cursor:** add `"artifacto": { "url": "https://artifacto.bstock.io/mcp" }` under `mcpServers` in `~/.cursor/mcp.json`; Cursor starts the sign-in.
   - **VS Code:** `code --add-mcp '{"name":"artifacto","type":"http","url":"https://artifacto.bstock.io/mcp"}'`; VS Code starts the sign-in.
   - **Anything else:** any MCP client with Streamable HTTP and OAuth works with the URL above.
2. **The sign-in:** a browser tab opens on Artifacto; the person signs in with their B-Stock Google account if asked and clicks **Approve**. Being signed in to the Artifacto website on its own does not connect you.
3. **Get the tools into this chat.** A chat that was already running when Artifacto was added often does not get the tools. If you do not have them now, tell the person to start a new chat and paste the same line there. In a desktop app (Claude Desktop, ChatGPT desktop) a new chat is not enough: they must quit and reopen the app first.
4. **Check it works:** call the `search` tool with no arguments and tell them how many items they can see. Only a successful call proves it works: a saved server or a finished sign-in does not. Do not tell them it is connected before this.
5. **Offer next steps:** publishing something they are working on, or finding something that already exists.

## Tools

- `search`: search or list what the person can see (`query`, `type`, `path`, `deleted`).
- `list_paths`: the folder paths that hold something the person can see.
- `get_item`: read one item in full.
- `publish_artifact`, `publish_document`: publish something NEW.
- `publish_version`: update an existing item in place (same link, new version). It also restores a deleted item.
- `move`, `delete`: for items the person owns. Deleted items are kept and can be restored.

## Rules for publishing

- An artifact is **one self-contained HTML page**: CSS and JS inline, images as `data:` URLs or inline SVG. No CDNs, remote fonts, remote images or fetch calls: the viewer blocks all network access. WebRTC, DNS prefetch and anything that looks like a secret are refused.
- Links to other sites need `target="_blank" rel="noopener"`. Do not make the page reload or navigate itself; use #hash links or JS state for tabs.
- Every publish needs a **visibility**: `org` (everyone at B-Stock), `space` (the members of its space), `restricted` (only the person) or `list` (the person plus `share_with`). If they have not said, ask.
- Folders are paths like `Seller Ops/Q4 audits`, where the first part is the space. The person can publish and move only into spaces they are a member of (`list_paths` shows them); inside one, any missing folder is made. Only admins make new spaces. No path means the shared Scratch pad, open to everyone.
- To change something, publish a new version of it with `publish_version` and its id. Never publish a copy. Keep the `id` each publish returns: titles are not unique, so the id is the only reliable way back to the item.
- After publishing, give the person the link.

## If your client cannot do MCP

Agents that run as scheduled jobs use the REST API under `https://artifacto.bstock.io/v1` with a per-consumer secret instead. See the README of the artifact-repo project, or ask the Artifacto maintainers for a secret.