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

# Troubleshooting

> Fix the common Artifacta MCP install failures: unauthorized errors, npx/PATH issues, server disconnected, and an empty tool list.

The three failures below cover nearly every install problem in Claude Desktop,
Claude Code, Cursor, and Codex. Each maps to a concrete fix.

## `unauthorized` on every call

The server returns `unauthorized` when the Artifacta API rejects the configured
key. Common causes, in order of likelihood:

1. **`ARTIFACTA_API_KEY` is not exported to the host.** Editing your shell's
   `.zshrc` or `.bashrc` does **not** propagate to Claude Desktop or Cursor —
   they read the `env` block from your `mcpServers` config, not your interactive
   shell. Put the key directly in the host's config file
   (`claude_desktop_config.json` or `~/.cursor/mcp.json`) and restart the host.
   For Claude Code, `${ARTIFACTA_API_KEY}` expands from the shell that launches
   `claude` — make sure you `export` it in that shell.
2. **Wrong scope or rotated key.** The remediation message includes the
   last-known key suffix (`Last-known key suffix: ****abcd`). If that suffix does
   not match the key in your [dashboard](https://app.artifacta.io/dashboard/keys),
   the key was rotated or you pasted the wrong one — regenerate or paste the
   current key and restart.
3. **Malformed key.** Keys must match `ak_live_` plus exactly 32 alphanumeric
   characters. If the shape check fails, the server exits at startup with code 2
   — check the host's stderr log for the rejection message.
4. **Tenant in deletion grace period.** The remediation becomes `"Account is
   scheduled for deletion — see https://app.artifacta.io/dashboard/account."`
   Restore the account from the dashboard before the grace period ends.

If none apply, capture the failing response — every error result carries a
`request_id` in `_meta.request_id` — and contact support with that id.

## `npx not found` — Node is not installed (or not on the host PATH)

If the host log shows `npx: command not found`, **`Failed to spawn process: No
such file or directory`** (when `"command"` is a bare or absolute path to
`npx` that does not exist on disk), or the server simply never starts and no
Artifacta tools appear, Node.js is not installed, not on the host's `PATH`, or
the config points at the **wrong** `npx` binary.

* **Install Node.js 20 or newer** from [nodejs.org](https://nodejs.org) or via a
  version manager (`nvm install 20`, `brew install node`). `npx` ships with
  Node, so installing Node fixes this.
* **Verify** from a shell: `node --version` should print `v20.x` or higher, and
  `npx --version` should print a number.
* **Confirm the package resolves:** `npx -y @artifacta-mcp/mcp --version` should
  print `1.0.0`.
* **Shell works, Claude Desktop / Cursor does not:** macOS GUI apps don't
  inherit your shell `PATH`, so nvm/fnm/asdf-installed `npx` is invisible to
  them. See [Server disconnected](#server-disconnected--failed-to-spawn) for
  the fix. The official Node installer and Homebrew Node put `npx` on the
  default GUI `PATH`, so bare `"command": "npx"` usually works with them.

The package's `engines.node` is `>=20.0.0`; on Node 18 or older the install step
**refuses to run** before any tool executes.

## Server disconnected / failed to spawn

Claude Desktop or Cursor shows **Server disconnected**, **Could not attach to
MCP server**, or the log (`~/Library/Logs/Claude/mcp-server-artifacta.log` on
macOS) contains **`Failed to spawn process: No such file or directory`** right
after launch.

| Log / UI signal                                      | Likely cause                                                                   | Fix                                                                                                                                                                                                      |
| ---------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Failed to spawn process: No such file or directory` | `"command"` path wrong (common: `/opt/homebrew/bin/npx` when Node is nvm-only) | Run `which npx` or `which artifacta-mcp`; paste exact path into `"command"`                                                                                                                              |
| Server disconnects instantly; no Artifacta tools     | Same as above, or bare `npx` not on GUI `PATH`                                 | [Absolute `npx`](/mcp/install/claude-desktop#when-npx-works-in-terminal-but-not-in-claude-desktop) or [global install](/mcp/install/claude-desktop#alternative-global-install-recommended-for-nvm-users) |
| `node: bad option: -y`                               | `"command"` is `node` but `args` start with `-y` (npx flags passed to node)    | Use `"command": "npx"` (or full path to npx), not `node`, for `-y @artifacta-mcp/mcp`                                                                                                                    |
| Tools empty; stderr mentions `engines`               | Node \< 20                                                                     | Upgrade to Node 20+                                                                                                                                                                                      |
| `unauthorized` on first tool call                    | Key missing/wrong in host `env` block                                          | Put `ARTIFACTA_API_KEY` in `mcpServers.artifacta.env`, not only in shell                                                                                                                                 |

After any config change, **fully quit and restart** the host (Cmd+Q on macOS for
Claude Desktop — closing the window is not enough).

## `tools/list` is empty — the server failed to start

If Claude reports no Artifacta tools at all, the host launched but the server
process did not come up. Check the host's MCP / developer logs:

* **Claude Desktop:** **Settings → Developer** shows server status; the log files
  live at `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\`
  (Windows). Look for the `artifacta` server's stderr.
* **Claude Code:** run `claude mcp list` to confirm `artifacta` is registered,
  and check the session output for the server's startup errors.
* **Cursor / Codex:** check the client's MCP log panel.

Common root causes:

* **`npx` could not resolve `@artifacta-mcp/mcp`** — no network, or a stale npm
  cache. Reproduce with `npx -y @artifacta-mcp/mcp --version` from a shell; if
  that hangs or errors, fix connectivity / clear the cache (`npm cache clean --force`).
* **Node 18 or older** — the `engines` gate refuses the install. Upgrade to
  Node 20+ (see above).
* **A startup flag rejected the launch.** A relative `--allow-path` value, or a
  malformed API key, makes the server exit with code 2 at startup before
  registering any tools. The stderr log names the exact reason — fix the flag or
  key and restart.
* **JSON syntax error in the config file.** A trailing comma or missing brace in
  `claude_desktop_config.json` / `.mcp.json` stops the host from launching the
  server. Validate the file.

## Destructive tools missing from `tools/list`

If `create_download_link`, `delete_artifact`, or `seal_session` is missing while
every other Artifacta tool appears, you are on a **non-compliant client**
(Claude Desktop, Cursor, Codex) without `--allow-destructive` in the launch
`args`. Those hosts don't implement MCP write confirmations, so the server hides
destructive-classified tools by default. Add `"--allow-destructive"` to the
`args` array, restart the host, and confirm the tool appears. See the [autonomy
boundary](/mcp/overview#autonomy-boundary) for the full compliant /
non-compliant matrix.

For `create_download_link` specifically: `get_artifact_download_url` is **not** a
substitute — it returns a time-limited presigned URL for the authenticated
caller, not a public share link.

## Path arguments are refused even though the file exists

`store_artifact.path` is guarded by the local path-confinement engine. It
refuses any path **outside the allow-list** (default: the server's working
directory) and any path **inside the built-in deny-list** (`~/.ssh`, `~/.aws`,
`~/.gnupg`, `~/.config/gh`, `~/.kube`, `~/.netrc`, `~/.artifacta`, `/etc`,
`~/Library/Keychains`, any `credentials.json`, any `.env*`) — even when the
allow-list is widened, because **the deny-list always wins**.

* Pass `--allow-path=/your/absolute/dir` at launch to extend the allow-list.
  Relative values exit at startup with code 2. The CLI flag is not inferred
  from a config-file field, but the server **also** widens the 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`.
* Symlinks are resolved with `realpath()` before the check, so a symlink
  pointing outside the allow-list (or into the deny-list) is refused after
  resolution.
* Sockets, FIFOs, and device files are refused.
* Files over the **500 MB** ceiling are refused — switch to `request_upload_url`
  → `complete_upload` for larger uploads.

See [Path confinement and `--allow-path`](/mcp/overview#path-confinement-and-allow-path)
for the full configuration reference.