Skip to main content

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.

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 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. 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 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:
claude_desktop_config.json
{
  "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.
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 or a global install instead. Official Node from nodejs.org or brew install node usually works as-is.
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.

​
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): 
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):
claude_desktop_config.json
{
  "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 is usually more reliable than chasing nvm’s per-version npx path on every Node upgrade. Install once, then point "command" at the global binary — no npx fetch on every Claude restart, and no dependency on GUI PATH resolution: 
npm install -g @artifacta-mcp/mcp@1.0.0
which artifacta-mcp    # copy this path into "command"
artifacta-mcp --version
claude_desktop_config.json
{
  "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

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 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:
claude_desktop_config.json
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/uploads"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
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.

​
--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:
claude_desktop_config.json
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/uploads", "--allow-destructive"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
--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 for the full matrix.

​
First call: the whoami smoke test

After restarting, confirm the install end-to-end:
  1. Configure the 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:
    whoami response
    {
  "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 — especially npx not found and Server disconnected. 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.

​
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.
FieldStatus
Submission prepared2026-05-29
Current statusPending — 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 above is the install path.

​
Troubleshooting

See the dedicated 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).