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

# Install in Cursor

> Paste one MCP block into Cursor's mcp.json and use Artifacta tools from the inline AI chat.

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](https://app.artifacta.io/dashboard/keys) — 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:

```json ~/.cursor/mcp.json theme={null}
{
  "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).

<Warning>
  **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](/mcp/install/claude-desktop#alternative-global-install-recommended-for-nvm-users).
  Full diagnosis: [Server disconnected](/mcp/troubleshooting#server-disconnected--failed-to-spawn).
</Warning>

<Note>
  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.
</Note>

## 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](/mcp/troubleshooting#path-arguments-are-refused-even-though-the-file-exists)
defaults its allow-list to the server's working directory; add the directory
your generated files land in:

```json ~/.cursor/mcp.json theme={null}
{
  "mcpServers": {
    "artifacta": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp", "--allow-path", "/Users/you/project/out"],
      "env": { "ARTIFACTA_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

<Warning>
  **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`.
</Warning>

### `--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:

```json ~/.cursor/mcp.json theme={null}
{
  "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" }
    }
  }
}
```

<Warning>
  **`--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](/mcp/overview#autonomy-boundary) for the full matrix.
</Warning>

## First call: the `whoami` smoke test

After Cursor shows the `artifacta` server connected:

1. Configure the [canonical config](#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:

   ```json whoami response theme={null}
   {
     "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](/mcp/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.

| Field                                               | Value                                                                                          |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Config format last reviewed against Cursor MCP docs | 2026-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.

<Note>
  If a future Cursor release changes the MCP config shape (e.g. a new key name or
  file location), update the [canonical config](#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.
</Note>

## Troubleshooting

See the dedicated [Troubleshooting](/mcp/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`).