> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install in Claude Desktop

> Copy one JSON block into claude_desktop_config.json and store artifacts from a Claude Desktop conversation.

This page gets you from a fresh Artifacta API key to your first tool call in
Claude Desktop in under five minutes. If you also use Claude Code, Cursor,
Codex, or another MCP host, see the [Overview](/mcp/overview) for every client.

## Prerequisites

* **Node.js 20 or newer.** The `@artifacta-mcp/mcp` package's `engines` field
  rejects earlier versions before any tool runs. Confirm with `node --version`.
* **An Artifacta API key.** Create one on the [API keys
  page](https://app.artifacta.io/dashboard/keys). The key shape is `ak_live_`
  followed by 32 alphanumeric characters.
* **Claude Desktop** installed (macOS or Windows).

There is nothing to install globally for the default path — `npx` fetches and
runs the published server on demand. If `npx` works in your terminal but
Claude Desktop still cannot start the server, see [When `npx` works in Terminal
but not in Claude Desktop](#when-npx-works-in-terminal-but-not-in-claude-desktop)
below.

## Canonical config

Open Claude Desktop → **Settings** → **Developer** → **Edit Config**. The file
lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on
macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Add an
`artifacta` entry under `mcpServers`:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

This block works for most installs — the only edit you need is pasting your real
`ak_live_…` key in place of the placeholder. Save the file and **fully restart
Claude Desktop** (quit, don't just close the window) so it relaunches the
server.

<Warning>
  **macOS: Claude Desktop does not inherit your shell `PATH`.** If Node was
  installed via **nvm**, **fnm**, or **asdf**, bare `"command": "npx"` may show
  **Server disconnected** even when `npx` works in Terminal. Use the
  [absolute `npx` path](#when-npx-works-in-terminal-but-not-in-claude-desktop) or
  a [global install](#alternative-global-install-recommended-for-nvm-users)
  instead. Official Node from [nodejs.org](https://nodejs.org) or
  `brew install node` usually works as-is.
</Warning>

<Note>
  The snippets here leave `@artifacta-mcp/mcp` unpinned so `npx` resolves the
  latest published release on each restart — patch and security fixes roll out
  without a config edit. Pin to a specific version (e.g.
  `@artifacta-mcp/mcp@1.0.0`) only for a frozen, managed deployment.
</Note>

## When `npx` works in Terminal but not in Claude Desktop

Symptoms in **Settings → Developer** or `~/Library/Logs/Claude/mcp-server-artifacta.log`:

* `Failed to spawn process: No such file or directory` — often a **wrong**
  absolute path in `"command"` (e.g. Homebrew `npx` when Node is from nvm).
* `Server disconnected` immediately after reload — same root cause, or `npx`
  not on the GUI app's `PATH`.

**Diagnose in Terminal** (must succeed before editing Claude config):

```bash theme={null}
npx -y @artifacta-mcp/mcp --version   # expect: 1.0.0
which npx                               # copy this path exactly
```

Substitute the absolute `npx` path from `which npx` into `"command"` (keeps
the on-demand `npx` flow):

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "@artifacta-mcp/mcp"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

For nvm setups, a [global install](#alternative-global-install-recommended-for-nvm-users)
is usually more reliable than chasing nvm's per-version `npx` path on every
Node upgrade.

## Alternative: global install (recommended for nvm users)

Install once, then point `"command"` at the global binary — no `npx` fetch on
every Claude restart, and no dependency on GUI `PATH` resolution:

```bash theme={null}
npm install -g @artifacta-mcp/mcp@1.0.0
which artifacta-mcp    # copy this path into "command"
artifacta-mcp --version
```

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/artifacta-mcp",
      "args": [],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Append `--allow-path` / `--allow-destructive` to `"args"` exactly as in
[Optional flags](#optional-flags).

## Optional flags

Two launch flags extend what the server can do. Both belong in the same `args`
array, after the package name.

### `--allow-path` — upload local files

`store_artifact` can stream a file from disk (`path` argument) instead of
inline `content`. The [path-confinement
engine](/mcp/troubleshooting#path-arguments-are-refused-even-though-the-file-exists)
restricts which directories it may read. By default the allow-list is **only
the server's working directory**, which for a Claude Desktop launch is not a
location you control — so add the directory your generated files land in:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/uploads"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

<Warning>
  **Scope `--allow-path` as narrowly as the work allows.** It grants the agent
  read access to every file under that directory (subject to the built-in
  deny-list, which always wins — `~/.ssh`, `~/.aws`, `/etc`, any `.env*` or
  `credentials.json`, etc.). Point it at a dedicated `uploads/` or build-output
  directory, **not** at your home directory or a source tree full of secrets.
  The flag accepts **absolute paths only**; a relative value exits at startup
  with code 2. The CLI `--allow-path` flag itself is not inferred from a
  config-file field, but the server **also** widens its allow-list from the
  **`ARTIFACTA_MCP_ALLOW_PATH`** environment variable (colon-separated absolute
  paths) when present in the launched server's `env` block — audit it alongside
  `args` whenever you review who can read local files through
  `store_artifact.path`.
</Warning>

### `--allow-destructive` — expose destructive tools

Claude Desktop does not advertise MCP write confirmations, so three tools —
`create_download_link` (mints a **public** `dl.artifacta.io/lnk_…` URL),
`delete_artifact` (soft-deletes by id), and `seal_session` (marks a session
**irreversible** — no `unseal`) — are **hidden from `tools/list` by default**.
Add `--allow-destructive` to expose them:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/uploads", "--allow-destructive"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

<Warning>
  **`--allow-destructive` removes the only barrier between the agent and
  irreversible actions on Claude Desktop.** Because the host shows no
  confirmation UI, each destructive call instead emits a one-line stderr audit
  (`[artifacta-mcp] destructive call: <tool>(<args>)`) and runs. With it set, an
  agent can publish a public share link, delete an artifact, or permanently seal
  a session without prompting you first. Only enable it if you intend to approve
  these actions in chat before the agent runs them, and never set it for an
  unattended agent. The flag is **never read from the environment or any config
  file** — it must be in the launch `args`. See the [autonomy
  boundary](/mcp/overview#autonomy-boundary) for the full matrix.
</Warning>

## First call: the `whoami` smoke test

After restarting, confirm the install end-to-end:

1. Configure the [canonical config](#canonical-config) above with your real key.

2. **Fully restart Claude Desktop.**

3. In a new conversation, ask:

   > "What's my Artifacta plan?"

4. **Expected:** Claude invokes the `whoami` tool and reports your tenant info —
   plan tier (e.g. `free`), storage usage, and request quota — back in the
   conversation. A response looks like:

   ```json whoami response theme={null}
   {
     "tenant_name": "maya",
     "plan": "free",
     "api_key_last_4": "abcd",
     "usage_storage_bytes": 1048576,
     "plan_storage_limit_bytes": 1073741824,
     "usage_requests_month": 142,
     "plan_requests_limit_month": 10000
   }
   ```

If Claude says it has no Artifacta tools, returns an `unauthorized` error, or
shows **Server disconnected** for the `artifacta` MCP entry, work through
[Troubleshooting](/mcp/troubleshooting) — especially [`npx` not
found](/mcp/troubleshooting#npx-not-found--node-is-not-installed) and [Server
disconnected](/mcp/troubleshooting#server-disconnected--failed-to-spawn).

`whoami` has no side effects and is quota-cheap, so it is the right tool to
verify auth before the agent does anything else. From here, ask it to
`list_artifacts`, `store_artifact`, and more — see [Using Artifacta from your
coding agent](/mcp/overview#using-artifacta-from-your-coding-agent).

## Discoverability — Anthropic MCP directory

Artifacta is being submitted to Anthropic's MCP directory so Claude Desktop
users can discover and install it without reading docs first.

| Field               | Status                                                    |
| ------------------- | --------------------------------------------------------- |
| Submission prepared | 2026-05-29                                                |
| Current status      | Pending — awaiting Anthropic directory eligibility review |

Eligibility criteria and listing decisions are controlled by Anthropic and may
change; this row is updated when the listing goes live. Until then, the manual
[canonical config](#canonical-config) above is the install path.

## Troubleshooting

See the dedicated [Troubleshooting](/mcp/troubleshooting) page, which covers
the three most common failures: `unauthorized` on every call, `npx` not found
(Node not installed), and an empty tool list (the server failed to start).