MCP server

Connect an MCP host to Artefaktum's hosted server and use six tools to find, read, save and trust artifacts.

Connecting

Artefaktum runs one hosted MCP server over Streamable HTTP:

https://api.artefaktum.dev/mcp

No stdio entry point; a stdio-only host needs a bridge such as mcp-remote.

Claude Code:

claude mcp add --transport http artefaktum https://api.artefaktum.dev/mcp

Cursor, Windsurf, Cline, or any host that reads an mcp.json:

{ "mcpServers": { "artefaktum": { "url": "https://api.artefaktum.dev/mcp" } } }

What happens on first use

The host opens a browser tab for an OAuth 2.1 sign-in handled by Clerk: sign in with Google or GitHub, approve the connection once, and the host gets an access token it attaches to every call after that. There is no key to paste. Sign-in provisions a tenant the first time it happens, keyed to your personal account or Clerk organisation, with a default project already in place.

Authentication

The endpoint accepts two bearer credentials, checked by the same resolver chain as REST:

  • OAuth 2.1 access token: issued by Clerk after the browser sign-in above. The default for hosts with an OAuth-capable MCP client.
  • API key: the same key used against the REST API, created in the console, sent as Authorization: Bearer <key>. Use it for hosts that can’t complete a browser flow, or for unattended runs: pass --header on claude mcp add, or add a header next to url in mcp.json if the host allows one.

Two OAuth caveats: Clerk’s tokens carry no audience (aud) claim, so audience checking is relaxed rather than strict; and Clerk doesn’t know Artefaktum’s scope names, so every OAuth caller gets a fixed grant of read, write and search, never delete or admin. An API key carries exactly the scopes it was minted with. Neither matters for normal use, only for auditing what an OAuth agent can reach.

Tools

Six tools. Every tool except project_list takes an optional project (a slug or UUID). Without it the tools use your API key’s project if it is project-scoped, else the project with slug default; call project_list to see the others. List-shaped results cap at 25 items and long text is truncated.

Tool Purpose
artifact_search Find artifacts by meaning, text, or structured filters.
artifact_get Read one artifact by ID or by key: details, trust signals, relations and the content itself.
artifact_put Save text or JSON, optionally under a key to add a version or reuse an existing result.
artifact_update Change an artifact’s title, description, tags, metadata or expiry.
artifact_delete Request permanent deletion of an artifact.
project_list List the projects this credential can use.

What changed

Text content now comes back inline in artifact_get, and artifact_put takes text directly, so chat hosts, which cannot make HTTP requests to a signed URL, now work end to end: they can search, read, and save. Binary files still go through a short-lived download URL, and uploading them stays with the SDKs, the CLI and REST. The upload, download-URL, list, resolve, version and relation tools are gone; their jobs are artifact_put, artifact_get and artifact_search. Relations remain readable in artifact_get; writing them stays in REST, the SDKs and the CLI.

Finding artifacts

artifact_search matches descriptors (title, description, tags, metadata), never file contents. mode is exact (filters only), text (full-text), semantic (pgvector) or hybrid (fuses both; the default). Scores aren’t comparable across modes. Superseded artifacts are hidden unless asked for.

Parameter Type Default
project slug or UUID default
query string ""
mode string "hybrid"
tags_all string[] none
content_types string[] none
exclude_superseded boolean true
limit integer 20 (capped at 25)
{ "query": "q3 churn analysis", "mode": "hybrid", "tags_all": ["churn"], "limit": 10 }

Reading

artifact_get returns one artifact: details, lifecycle state, trust signals, up to 25 relations and the content. Give exactly one of artifact_id or key.

Parameter Type Default
artifact_id UUID one of artifact_id / key
key string one of artifact_id / key
project slug or UUID your API key’s project if project-scoped, else default
max_age_seconds integer none; with key, an older artifact is reported as not found
include_content boolean true
max_characters integer 50000
version_id UUID latest version

Text-like files up to 5 MiB come back inline as content, with content_truncated, content_characters and content_version_id (the version actually read). Anything else returns content: null and a content_reason:

content_reason Meaning
binary Not text; use download_url (with download_expires_at).
too_large Text over 5 MiB; use download_url.
not_requested include_content was false.
not_ready The upload is still processing; read again shortly.
{ "key": "report:sales", "project": "finance", "max_age_seconds": 86400 }

project_list takes no arguments; it returns every project the credential can use.

Saving

artifact_put saves text or JSON as an artifact. content is at most 1 MiB of UTF-8; larger or binary files go through the SDKs or CLI. The /mcp request body limit is 2 MiB; REST stays at 256 KiB.

Parameter Type Default
content string required
title string required
project slug or UUID your API key’s project if project-scoped, else default
key string none
if_exists error / version / reuse error
max_age_seconds integer none (only with reuse; an older artifact counts as missing)
filename string generated
content_type string text/plain
description string ""
tags string[] none
metadata object none
expires_in_hours integer none (applied whenever this call stored bytes: a new artifact, a new version, or a reuse that replaced a stale copy; never on a reuse hit)
run_id string none

With a key, if_exists chooses what a repeat does: error refuses, version adds a new version under the same key, reuse returns the existing artifact with cache: "hit" and writes nothing, or stores yours with cache: "created". The result may still show processing; search finds it once it is ready. Field sizes are limited; see Limits.

{
  "title": "Acme enrichment",
  "key": "company-api/acme/2026-10-24",
  "if_exists": "reuse",
  "max_age_seconds": 86400,
  "content": "{\"employees\": 120}",
  "content_type": "application/json"
}

Changing and deleting

artifact_update changes title, description, tags, metadata or expiry (expires_at, or clear_expires_at). Find the artifact by artifact_id or by key (with project). Bytes are immutable: for new content call artifact_put with if_exists: "version".

artifact_delete moves the artifact to deleting; a worker removes the bytes. Not reversible. Same lookup: artifact_id, or key with project.

The artifact resource

artefactai://artifacts/{artifact_id} is a pointer, not a data endpoint. A resource read carries no principal to authorize against, so it returns only the id you gave it plus a nudge to call artifact_get instead.

Typical agent flow

A research agent hands a report to a writing agent, neither knowing where the other runs.

  1. Research agent calls artifact_put with the report text, a title and a key, if_exists: "version", so reruns add versions.
  2. Writing agent, on a separate host, calls artifact_search (hybrid, same project) and picks a hit with superseded: false and stale_upstream: false.
  3. Writing agent calls artifact_get and reads content inline. If content_reason is not_ready, it reads again a moment later.
  4. Writing agent saves its own output with artifact_put, tagged with the same run_id. Reading through MCP does not infer lineage, so no derived_from edge appears on its own; relations show up in artifact_get, and writing one goes through REST, the SDKs or the CLI.

This page as Markdown: /docs/mcp.md