# SagaPeak/artifacta-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/SagaPeak/artifacta-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 426  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sagapeak-artifacta-mcp

## Description
The artifact store for AI agents. Every output your agents produce — persisted, retrievable, shareable. Across runs, sessions, and tools. Session/agent metadata, content-hash dedup, expiring share links; 11 tools with path-confined uploads and destructive actions gated by default. TypeScript (npx @artifacta-mcp/mcp) and Python (pipx run artifacta-mcp).

## Tools
Capabilities this server exposes over MCP:

- **whoami** — Return the calling tenant's identity, plan tier, current usage counters (storage bytes, monthly requests, active links), and rate limits. Use this once at the start of an agent run to confirm authentication and to size subsequent operations against quota. Free of side effects and quota-cheap.
- **list_artifacts** — List artifacts owned by the calling tenant, newest first. Supports filters by `session_id`, `agent_id`, `filename` (exact match), `content_type`, `created_after` / `created_before` (ISO 8601), and one or more `metadata.<key>=<value>` pairs (multi-key requires Pro). Returns a page of artifact records and a `next_cursor` to fetch the next page. Use this to discover what an agent or pipeline produced when you only know a session or agent ID.
- **get_artifact** — Fetch metadata for a single artifact by ID: filename, content type, size, content hash, session/agent IDs, custom metadata, expiry, creation timestamp. Does NOT return the file bytes — call `get_artifact_download_url` for that. Returns `artifact_not_found` for unknown IDs, `artifact_already_deleted` (HTTP 410) for soft-deleted ones, `artifact_expired` (410) for those past their TTL.
- **get_artifact_download_url** — Generate a short-lived presigned URL (1 hour) the agent can use to download the artifact's bytes directly from Cloudflare R2. Use this when the agent itself needs to consume the file. For sharing with humans, use `create_download_link` instead — that produces a stable `dl.artifacta.io/lnk_…` URL with configurable expiry.
- **list_sessions** — List session IDs synthesized from the calling tenant's artifacts, ordered by most recent activity. Each entry includes artifact count, seal status, and first/last activity timestamps. Sessions are not first-class — they exist only as long as artifacts reference them.
- **store_artifact** — Upload a file as a new artifact in a single call. Provide EITHER up to ~10 MB of base64-encoded bytes via `content`, OR a local filesystem `path` that the MCP server reads and streams as multipart/form-data (up to 500 MB). For files larger than 500 MB, use `request_upload_url` (Pro only) instead — `store_artifact` returns `file_too_large` for them. Tags the artifact with `session_id` / `agent_id` / `metadata` for later retrieval and returns the full artifact record including its new `artifact_id` and `content_hash`.

Path uploads are confined. The `path` argument is constrained to the launcher-configured allow-list (default: the MCP server's CWD). Paths outside the allow-list, paths traversing symlinks out of it, and paths to known-sensitive locations (`~/.ssh`, `~/.aws`, `/etc/`, etc.) are refused with `invalid_request`.

For crash-safe retries, supply your own `idempotency_key` (any string ≤256 chars): a replay within 24h returns the original artifact and never double-bills. If you omit it, the server auto-generates one and returns it under `_meta.idempotency_key`, but that key protects only in-process retries within a single call — it is lost if the server restarts, so pre-commit your own key when durability matters.
- **request_upload_url** — Reserve a presigned R2 PUT URL for a file too large to send through `store_artifact` (over 500 MB up to 5 GB). Returns an `upload_url`, headers to include in the PUT, and an `artifact_id` in `pending` state. The agent (or its environment) PUTs the bytes directly to R2, then calls `complete_upload`. Pro plan only. Most agents should use `store_artifact` and let the MCP server pick the path automatically.

Not retry-safe: this endpoint does not support idempotency keys, so on an HTTP 5xx or network error the reservation may or may not have been created. Do NOT blindly retry — the error guidance tells you to first call `list_artifacts` with the same `session_id`/`agent_id` to detect any pending artifact, so you don't create a duplicate.
- **complete_upload** — Finalize an artifact previously reserved via `request_upload_url` after the bytes have been PUT to the presigned URL. Server verifies the blob, computes the content hash, transitions the artifact from `pending` to `active`, and increments tenant usage. Calling this on an already-active artifact is idempotent and returns the existing record. Calling before the PUT completes returns `upload_not_found` — wait and retry.
- **publish_artifact** — Publish an existing artifact as a polished, shareable public page at https://artifacta.io/a/{slug}. Composes with store_artifact (store first, then publish). Returns a public_url anyone can open without an Artifacta account. Default visibility is unlisted (link-only); pass visibility:"public" for gallery-eligible later. Idempotent: re-publishing the same artifact_id updates the existing page and keeps the same URL.
- **unpublish_artifact** — Remove the public page for an artifact, making the public URL inaccessible. The artifact itself is not deleted — only its shareable page is taken down. The URL stops resolving immediately. Idempotent: calling unpublish on an already-unpublished artifact is a no-op.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "artifacta-mcp": {
    "command": "npx",
    "args": ["-y","@artifacta-mcp/mcp"],
    "env": {
      "ARTIFACTA_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `ARTIFACTA_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What SagaPeak/artifacta-mcp MCP server does

SagaPeak/artifacta-mcp MCP server exposes Artifacta as an MCP-based artifact store for AI agent workflows. It persists files and other outputs with artifact IDs, content hashes, filenames, content types, timestamps, session IDs, agent IDs, and custom metadata. Agents can later discover those records without relying on the original conversation or process.

The server supports both private retrieval and controlled sharing. An agent can obtain artifact metadata, request a one-hour presigned URL for the bytes, create an expiring download link for people, or publish an artifact as a public page at `artifacta.io/a/{slug}`. Publishing is separate from storage and is unlisted by default; unpublishing removes the page without deleting the stored artifact.

## How it works

The same MCP tool surface is available through TypeScript and Python implementations. A hosted connection is available at `https://mcp.artifacta.io/mcp`; clients authenticate through OAuth Dynamic Client Registration with PKCE and a browser consent flow. Local or CI deployments run over stdio and authenticate with an `ARTIFACTA_API_KEY`.

For ordinary files, `store_artifact` accepts either base64 content of roughly 10 MB or a local path that the server streams as multipart data up to 500 MB. Larger files, up to 5 GB, use a two-step flow: reserve an upload URL, send the bytes directly to storage, then call `complete_upload`. The server verifies the uploaded object, calculates its content hash, and activates the artifact.

Artifacts can be grouped using session and agent identifiers. `list_artifacts` supports filters for those identifiers, exact filenames, content types, ISO 8601 date ranges, and metadata pairs. `list_sessions` derives session records from artifacts rather than maintaining sessions as independent objects.

## Setup and configuration

For a local MCP client, run the TypeScript package with `npx -y @artifacta-mcp/mcp` and provide `ARTIFACTA_API_KEY` in the client environment. The Python alternative is `pipx run artifacta-mcp`. The repository identifies Node 20+ and Python 3.10+ as the supported runtimes.

The hosted setup avoids local installation and uses the MCP endpoint directly. Claude Desktop, Claude Code, Cursor, and other MCP clients can use the local stdio configuration; the README specifically documents the API-key environment variable and hosted HTTP setup. Local path uploads are restricted by an `--allow-path` allow-list, which defaults to the server's current working directory.

## Tools and capabilities

- Confirm tenant identity, plan information, usage counters, and rate limits with `whoami`.
- Store, inspect, list, and download artifacts with `store_artifact`, `get_artifact`, `list_artifacts`, and `get_artifact_download_url`.
- Track recent artifact-based sessions with `list_sessions`.
- Handle large uploads with `request_upload_url` and `complete_upload`.
- Publish or remove public artifact pages with `publish_artifact` and `unpublish_artifact`.
- Use content-hash deduplication and caller-supplied idempotency keys for safer artifact retries.

## Limitations and notes

SagaPeak/artifacta-mcp MCP server does not return file bytes from `get_artifact`; agents must request a download URL. The regular storage operation is limited to approximately 500 MB for path uploads, while the direct-upload flow is limited to 5 GB and is available only on the Pro plan.

Path uploads cannot escape the configured allow-list, traverse symlinks outside it, or target known-sensitive locations such as `~/.ssh`, `~/.aws`, and `/etc/`. Destructive tools such as deletion, session sealing, and public download-link creation require the local `--allow-destructive` setting. Hosted OAuth instead applies read, write, and destroy scopes. Publishing and unpublishing are write operations but are not treated as destructive actions.

The large-upload reservation is not retry-safe: after a server or network failure, callers should inspect for an existing pending artifact before reserving another upload. For normal storage retries, provide an idempotency key when a restart-safe retry is important. SagaPeak/artifacta-mcp MCP server is released under the MIT license.

_Full upstream README: https://allmcps.com/mcp/sagapeak-artifacta-mcp/readme_