> ## 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 Code

> Wire the Artifacta MCP server into Claude Code with a committed .mcp.json or a vendored .mcp/servers/artifacta config.

<Note>
  **Most users should use the [hosted MCP endpoint](/mcp/install/claude-code-hosted)
  instead.** Connect Claude Code with a URL and a one-time browser login — no
  package install and no API key to copy. This page is the **advanced / CI**
  path: the local stdio package with an `ak_live_` API key, for CI, restricted
  networks, and explicit credential control.
</Note>

Claude Code is Artifacta's primary distribution surface — the "Maya, Solo Agent
Builder" persona is building agents *with* Claude Code today (plan §8.2 rank 1).
This page covers the project-scoped install most teams want plus the vendored,
version-pinned layout for stricter environments.

## Prerequisites

* **Node.js 20 or newer** (`node --version`). The package's `engines` field
  rejects older versions before any tool runs.
* **An Artifacta API key** from the [API keys
  page](https://app.artifacta.io/dashboard/keys) — shape `ak_live_` plus 32
  alphanumeric characters.
* **Claude Code** installed (`claude --version`).

`npx` fetches and runs the published `@artifacta-mcp/mcp` package on demand —
nothing to install globally.

## Canonical config — project `.mcp.json`

For a single project, drop a `.mcp.json` at the repo root and commit it so the
whole team picks up the server automatically:

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

Claude Code expands `${ARTIFACTA_API_KEY}` from the shell environment at launch,
so the literal key stays out of the committed file. Export it in the shell that
starts Claude Code:

```bash theme={null}
export ARTIFACTA_API_KEY="ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

This block works **as-is** — no edits beyond exporting your key.

### One-line equivalent

To register the server without hand-editing JSON, use the CLI:

```bash theme={null}
claude mcp add artifacta -- npx -y @artifacta-mcp/mcp
```

Then export `ARTIFACTA_API_KEY` in the same shell. Re-run with the flags below
appended after `@artifacta-mcp/mcp` to add `--allow-path` / `--allow-destructive`.

<Note>
  The snippets leave `@artifacta-mcp/mcp` unpinned so `npx` resolves the latest
  published release — patch and security fixes roll out without a config edit.
  Pin a version (e.g. `@artifacta-mcp/mcp@1.0.0`) for a frozen, managed install;
  the [version-pinned and vendored layouts](#version-pinned-and-vendored-layouts)
  below are the patterns for that.
</Note>

## Version-pinned and vendored layouts

Claude Code only loads MCP servers declared in the root [`.mcp.json`](#canonical-config-project-mcpjson)
(or registered with `claude mcp add`). Dropping an `mcpServers` block under
`.mcp/servers/artifacta/config.json` does **not** register a server — Claude
Code never reads that file. Use one of the two patterns below instead.

### Version-pinned via root `.mcp.json`

For most teams that just want a frozen release, pin the version in the
canonical `.mcp.json` and commit it:

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

Bumping the pin is a single edit to `.mcp.json`; rollback is `git revert`.

### Vendored binary under `.mcp/servers/artifacta/`

If your environment forbids resolving the package over the network at launch
(air-gapped CI, strict supply-chain policy, security-reviewed binaries only),
**vendor** the server's package or executable under `.mcp/servers/artifacta/`
and point the root `.mcp.json` at it. `.mcp/servers/artifacta/` is a code
location for the vendored release — not an MCP host config — so it never
contains an `mcpServers` block.

For example, after `npm install --prefix .mcp/servers/artifacta @artifacta-mcp/mcp@1.0.0`
the executable lives at `.mcp/servers/artifacta/node_modules/.bin/artifacta-mcp`.
Reference it from the loadable root `.mcp.json`:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "command": "./.mcp/servers/artifacta/node_modules/.bin/artifacta-mcp",
      "args": [],
      "env": {
        "ARTIFACTA_API_KEY": "${ARTIFACTA_API_KEY}"
      }
    }
  }
}
```

Commit the resolved files under `.mcp/servers/artifacta/` (or restore them in
CI from a lockfile) so every contributor runs the same audited binary. The
host-loaded config still lives in the root `.mcp.json`; `.mcp/servers/artifacta/`
is purely the vendoring location.

For most projects the unpinned [`.mcp.json`](#canonical-config-project-mcpjson)
above is simpler; reach for these layouts only when you need a frozen pin or
an offline-vendored binary.

## Optional flags

Both flags go in the `args` array (or after `--` in `claude mcp add`).

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

`store_artifact` can stream a file from disk (`path` argument). The
[path-confinement engine](/mcp/troubleshooting#path-arguments-are-refused-even-though-the-file-exists)
defaults its allow-list to the server's working directory; extend it to the
directory your build outputs land in:

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

<Warning>
  **Scope `--allow-path` as narrowly as possible.** It grants read access to
  everything under that directory (the built-in deny-list — `~/.ssh`, `~/.aws`,
  `/etc`, any `.env*` or `credentials.json` — always wins regardless). Point it at
  a dedicated build-output directory, not your whole project tree or home
  directory. The flag accepts **absolute paths only** (a relative value exits at
  startup with code 2). The CLI `--allow-path` flag 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

Whether destructive tools are gated depends on the host's declared
capabilities. **Claude Code advertises `experimental.confirmations`**, so
`create_download_link`, `delete_artifact`, and `seal_session` are **present by
default** and the host prompts you before each call — you do *not* need
`--allow-destructive` for them to appear. Non-compliant hosts (Claude Desktop,
Cursor, Codex) hide them unless the flag is set. The flag is included here for
parity and for non-compliant hosts that share this config:

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

<Warning>
  **On non-compliant hosts, `--allow-destructive` removes the confirmation
  barrier entirely** — destructive calls run with only a one-line stderr audit,
  no UI prompt. On Claude Code the host confirmation already protects you, so the
  flag changes nothing there. Never set it for an unattended agent on a
  non-compliant host. 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

1. Add the [canonical `.mcp.json`](#canonical-config-project-mcpjson) and export
   `ARTIFACTA_API_KEY`.

2. Start Claude Code in the project (`claude`). Approve the project's MCP server
   if prompted.

3. Ask:

   > "What's my Artifacta plan?"

4. **Expected:** Claude Code invokes the `whoami` tool and reports your tenant
   info — plan tier, storage usage, request quota — in the session:

   ```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 no Artifacta tools appear, or you get `unauthorized`, see
[Troubleshooting](/mcp/troubleshooting). You can also list registered servers
with `claude mcp list` to confirm `artifacta` is wired up.

## Troubleshooting

The dedicated [Troubleshooting](/mcp/troubleshooting) page 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 — check the
host logs).