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.

Cursor’s MCP support matches Claude Desktop’s, so wiring in Artifacta is a single config block — paste it, restart, and the tools appear in Cursor’s inline AI chat. This page is for the “Daniel, Startup Engineer” persona who lives in Cursor and wants artifact storage without leaving the editor.

​
Prerequisites

  • Node.js 20 or newer (node --version). The @artifacta-mcp/mcp 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.
  • Cursor with MCP support (Settings → MCP / Tools & Integrations).
npx fetches and runs the published server on demand — nothing to install globally.

​
Canonical config

Cursor reads MCP servers from mcp.json. Use the global file for every project or a project-scoped file for one repo:
  • Global: ~/.cursor/mcp.json (create it if it does not exist).
  • Project: .cursor/mcp.json at the repo root.
Cursor’s mcpServers block is close to Claude Desktop’s, with one mandatory difference: each STDIO server entry must declare "type": "stdio". Omitting it leaves the server unregistered (or stuck in a red state) in current Cursor builds even when the rest of the block is valid:
~/.cursor/mcp.json
{
  "mcpServers": {
    "artifacta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp"],
      "env": {
        "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
This block works for most installs — the only edit is pasting your real ak_live_… key. Save the file, then in Cursor open Settings → MCP and confirm the artifacta server shows a green / connected status (toggle it off and on, or restart Cursor, if it does not pick up the new file).
macOS GUI PATH: If Cursor shows Server disconnected but npx -y @artifacta-mcp/mcp --version works in Terminal (typical when Node is installed via nvm), paste the output of which npx into "command" or use a global install. Full diagnosis: Server disconnected.
The snippet leaves @artifacta-mcp/mcp unpinned so npx resolves the latest published release on restart — patch and security fixes roll out without a config edit. Pin a version (e.g. @artifacta-mcp/mcp@1.0.0) only for a frozen, managed install.

​
Optional flags

Both flags go in the same args array, after the package name.

​
--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; add the directory your generated files land in:
~/.cursor/mcp.json
{
  "mcpServers": {
    "artifacta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/project/out"],
      "env": { "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
Scope --allow-path as narrowly as the work allows. 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 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

Cursor 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:
~/.cursor/mcp.json
{
  "mcpServers": {
    "artifacta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/project/out", "--allow-destructive"],
      "env": { "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
--allow-destructive removes the only barrier between the agent and irreversible actions on Cursor. 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 — the agent can publish a public share link, delete an artifact, or permanently seal a session without prompting you. Only enable it if you intend to approve these actions in chat first, and never 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 Cursor shows the artifacta server connected:
  1. Configure the canonical config with your real key.
  2. Restart Cursor (or toggle the server off/on in Settings → MCP).
  3. In the inline AI chat (agent mode), ask:
    “What’s my Artifacta plan?”
  4. Expected: the agent invokes the whoami tool and reports your tenant info — plan tier, storage usage, request quota — in the chat:
    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.

​
Smoke-test record

Cursor’s MCP config format has shifted between releases (notably the addition of "type": "stdio" as a required field on STDIO server entries), so the snippets above must be re-checked against the live Cursor build at each docs update and signed off by the operator.
FieldValue
Config format last reviewed against Cursor MCP docs2026-05-29 (file locations + mcpServers shape + required "type": "stdio" on STDIO entries)
Live smoke-test Cursor version[operator: fill version at HITL sign-off]
Live smoke-test date[operator: fill date at HITL sign-off]
Result[operator: PASS / FAIL recorded at sign-off]
Until the operator fills the three rows above with a real Cursor build, treat the canonical config as doc-reviewed but not live-validated for that specific release.
If a future Cursor release changes the MCP config shape (e.g. a new key name or file location), update the canonical config and this table. If the divergence from the Claude Desktop format is large enough to need a separate package configuration mode, that is a follow-up task — not a docs-only change.

​
Troubleshooting

See the dedicated Troubleshooting page, which covers unauthorized on every call, npx not found (Node not installed), an empty tool list (the server failed to start), and destructive tools missing from tools/list (add --allow-destructive).