io.artifacta/mcp

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.

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.

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

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.

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.

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.

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.

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.

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.