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

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

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

```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](https://artefaktum.dev/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) |

```json
{ "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. |

```json
{ "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](/docs/rest/#limits).

```json
{
  "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.
