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.

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 — 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:
.mcp.json
{
  "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: 
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: 
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.
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 below are the patterns for that.

​
Version-pinned and vendored layouts

Claude Code only loads MCP servers declared in the root .mcp.json (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:
.mcp.json
{
  "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:
.mcp.json
{
  "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 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 defaults its allow-list to the server’s working directory; extend it to the directory your build outputs land in:
.mcp.json
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/project/out"],
      "env": { "ARTIFACTA_API_KEY": "${ARTIFACTA_API_KEY}" }
    }
  }
}
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.

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

​
First call: the whoami smoke test

  1. Add the canonical .mcp.json 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:
    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 no Artifacta tools appear, or you get unauthorized, see Troubleshooting. You can also list registered servers with claude mcp list to confirm artifacta is wired up.

​
Troubleshooting

The dedicated 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).