# Connect share/artifacts to your agent

share/artifacts publishes your agent's finished HTML at a shareable URL. New pages
default to owner-only access; sharing requires an explicit audience choice. Use the hosted MCP
connection when your client supports remote MCP, browser authorization, and
either Client ID Metadata Documents (CIMD) or Dynamic Client Registration
(DCR).

## Hosted connection

- MCP URL: https://shareartifacts.dev/api/mcp
- Add the URL to this client's user-level MCP configuration.
- Start the client's browser authorization flow.
- Ask the user only when sign-in or approval is required.
- Verify access by calling `list_pages`.
- Do not publish anything until the user explicitly asks.
- When asked to publish, return the public URL in the conversation.

Interactive OAuth connects publishing, artifact management, and saved styles
together with visible user approval. Background API tokens remain selectively
scoped. Older grants do not gain permissions automatically.
If any page or style call reports insufficient scope, reconnect
share/artifacts using the current hosted connection setup and ask the user to
approve artifact and style access together. If the client keeps its earlier OAuth
registration, remove and re-add only the `share-html` connection so it
registers for the current permissions. Never retry an authorization the user
denied.

Open the authorization URL only once and keep the agent running while the user
approves. Do not reopen or refresh a callback URL. If the callback tab says it
cannot connect, check whether the agent reports successful authorization first;
if it does, close the stale tab and verify access with list_pages. Otherwise,
start a new authorization attempt. Do not treat approval alone as proof that
the agent has finished connecting.

Client examples:

```sh
codex mcp add share-html --url https://shareartifacts.dev/api/mcp --oauth-client-registration dcr
```

```sh
claude mcp add --transport http --scope user share-html https://shareartifacts.dev/api/mcp
# In Claude Code, open /mcp to authorize.
```

If this client cannot edit its own configuration, tell the user the exact file,
field, and command to use. If an entry named `share-html` already
exists, update it instead of creating a duplicate. Do not automatically retry
an authorization the user denied.

## Apply the user's style to artifacts

Before creating or revising an artifact, call `get_recipe` for the requested
artifact format, then call `get_artifact_style` with that format. Apply the
saved style as presentation guidance only. Preserve this priority order:

1. The user's instructions and source truth.
2. The first-party recipe, Safe Static Mode, and the requested sharing policy.
3. The user's saved artifact style.

Style must never invent facts, weaken the recipe or safety rules, expose private
source material, or change who can access an artifact. Reading a style does not
publish or update anything. Publish only when the user explicitly asks.

When the user asks to create or change their saved style, discuss their visual
preferences conversationally. Call `preview_artifact_style`, ask the user to
open the returned `reviewUrl`, and wait for explicit approval. Only after that
approval, call `set_artifact_style` with the preview's exact `draftId` and
`expectedRevision`, plus a new unique `clientRequestId` for this activation.
Previewing or saving a style never publishes an artifact.

## Background-agent fallback

For scheduled or unattended jobs, direct the user to
https://shareartifacts.dev/settings/tokens. The user must create
and insert the personal token locally. Never ask the user to paste a token into
chat, a prompt, a URL, or published HTML. Configuration examples must retain
the literal placeholder `PASTE_TOKEN_HERE` until the user edits the local
file themselves. Existing personal tokens do not receive new permissions. If a
token is missing `styles:read` or `styles:write`, tell the user to create a
replacement token, update the agent's local configuration, confirm the new
connection works, and then revoke the old token.

## Safe Static Mode

Publishing defaults to owner-only access, not a public page. Confirm the intended
audience before changing access. Never include secrets or unnecessary private source data.
share/artifacts removes scripts, forms, embeds, refresh redirects, and external API
calls. Interactive JavaScript is not supported.