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--headeronclaude mcp add, or add a header next tourlinmcp.jsonif 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.
- Research agent calls
artifact_putwith the report text, atitleand akey,if_exists: "version", so reruns add versions. - Writing agent, on a separate host, calls
artifact_search(hybrid, sameproject) and picks a hit withsuperseded: falseandstale_upstream: false. - Writing agent calls
artifact_getand readscontentinline. Ifcontent_reasonisnot_ready, it reads again a moment later. - Writing agent saves its own output with
artifact_put, tagged with the samerun_id. Reading through MCP does not infer lineage, so noderived_fromedge appears on its own; relations show up inartifact_get, and writing one goes through REST, the SDKs or the CLI.
This page as Markdown: /docs/mcp.md