Troubleshooting

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.

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, 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 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 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. 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 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 for the full configuration reference.