# artifyde-mcp

**A permanent home for your agent's HTML artifacts — over MCP.**

Your agent turns out real, finished work as rendered HTML: dashboards, prototypes, reports, decks. Normally those are disposable — a localhost link that dies, a file in a folder, gone on the next run. This [Model Context Protocol](https://modelcontextprotocol.io) server gives each one a permanent home on [Artifyde](https://artifyde.com): a stable link anyone can open, share, mark up, and version on every re-publish — without your agent leaving its MCP host.

It wraps the Artifyde API, so any MCP-capable client (Claude Desktop, Claude Code, Cursor, and others) can publish and manage artifacts directly.

## Install

The server runs over stdio and is launched with `npx`, so there's nothing to install globally. Add it to your MCP host's config.

### Claude Code

```bash
claude mcp add artifyde --scope user -e ARTIFYDE_TOKEN=vk_your_login_token -- npx -y artifyde-mcp
```

If you already use the `artifyde` CLI, pull the token straight from its store instead of pasting it:

```bash
claude mcp add artifyde --scope user \
  -e ARTIFYDE_TOKEN="$(jq -r '.servers["https://artifyde.com"].token' ~/.config/artifyde/config.json)" \
  -- npx -y artifyde-mcp
```

`--scope user` makes it available in every project; drop it to add for the current project only. Restart Claude Code (or run `/mcp`) to see the tools.

### Claude Desktop

Install the one-click bundle: download `artifyde-mcp.mcpb` from the [latest release](https://github.com/kennethkoontz/artifyde-mcp/releases/latest) and open it (Settings → Extensions), then paste your token in the extension's settings. Or add the JSON block below to `claude_desktop_config.json`.

### OpenAI Codex

```bash
codex mcp add artifyde --env ARTIFYDE_TOKEN=vk_your_login_token -- npx -y artifyde-mcp
```

Or in `~/.codex/config.toml` (shared by the Codex CLI and IDE extension):

```toml
[mcp_servers.artifyde]
command = "npx"
args = ["-y", "artifyde-mcp"]

[mcp_servers.artifyde.env]
ARTIFYDE_TOKEN = "vk_your_login_token"
```

### Cursor / other MCP hosts

Any host that takes an `mcpServers` JSON block:

```json
{
  "mcpServers": {
    "artifyde": {
      "command": "npx",
      "args": ["-y", "artifyde-mcp"],
      "env": {
        "ARTIFYDE_TOKEN": "vk_your_login_token"
      }
    }
  }
}
```

## Authentication

Set one credential in `env`:

- **`ARTIFYDE_TOKEN`** — a per-user login token (`vk_…`). Get one by installing the CLI (`npm i -g artifyde-cli`), running `artifyde login`, and copying the token from `~/.config/artifyde/config.json`. This is the recommended option: the server acts as **you**.
- **`ARTIFYDE_API_KEY`** — an admin shared-owner key (for programmatic/agent identities on self-hosted instances). A bearer token wins if both are set.

Without a credential the server still starts and can read **public** pages; publishing and private access require one.

By default the server talks to the hosted instance at `https://artifyde.com`. Point it elsewhere (e.g. a self-hosted or preview instance) with **`ARTIFYDE_URL`**.

## Tools

| Tool | What it does |
| --- | --- |
| `push_artifact` | Publish HTML → a stable view URL. Re-push to a `page_id` to add a version. |
| `pull_artifact` | Download a version's byte-exact HTML. |
| `get_page` | Page metadata + version history. |
| `list_pages` | Your pages, with version/comment counts (filter by archived / query). |
| `rename_page` | Set a page's display title. |
| `archive_page` / `unarchive_page` | Hide/restore a page (read-only when archived). |
| `get_share` | A page's visibility + invited-email list. |
| `set_visibility` | Make a page `public` or `private`. |
| `share_page` / `unshare_page` | Invite / revoke an email on a private page. |
| `list_comments` | Read a page's comment threads. |
| `create_comment` | Post a comment (or reply) on a version. |
| `list_shelves` / `create_shelf` | Manage gallery groupings. |
| `add_page_to_shelf` / `remove_page_from_shelf` | Organize pages onto shelves. |
| `whoami` | The identity the server is authenticated as. |

Every tool is annotated with `readOnlyHint`/`destructiveHint`/`idempotentHint` so hosts can gate confirmations appropriately.

## Privacy

This server is a thin client for the Artifyde API: the only data it transmits is what you ask it to (the HTML you publish, page ids, comment text, share emails), sent over HTTPS to the Artifyde server you configure (`https://artifyde.com` by default). Your token is read from the environment (or the Claude Desktop extension's config) and used solely to authenticate those API calls; nothing is logged or sent anywhere else. See the [Artifyde privacy policy](https://artifyde.com/privacy) for how the hosted service handles your data.

## Development

```bash
bun install
bun test              # unit tests (Bun's built-in runner)
bun run typecheck     # tsc --noEmit
bun run start         # run from source over stdio
bun run bundle        # build the Claude Desktop .mcpb bundle
```

The Artifyde API client under `src/core/` is vendored from the (private) Artifyde monorepo's `@artifyde/core` package; the API surface it wraps is the server's stable `/v1` contract.

See [`PUBLISHING.md`](./PUBLISHING.md) for the release + marketplace-listing runbook.

## Support

Issues and questions: [github.com/kennethkoontz/artifyde-mcp/issues](https://github.com/kennethkoontz/artifyde-mcp/issues)