Archivist AI MCP Server

The official Model Context Protocol (MCP) server for Archivist AI -- a TTRPG campaign memory platform for game masters and players.

Registry metadata lives in server.json. Publishing to the official MCP Registry is automated on version tags via .github/workflows/publish-mcp.yml (git tag v1.0.0 && git push origin v1.0.0).

Connect AI assistants like Claude, ChatGPT, Cursor, Notion, and Windsurf directly to your campaign data: characters, sessions, locations, factions, items, quests, journals, and more.

Quick Start

MCP Server URL: https://mcp.myarchivist.ai/mcp

{
  "mcpServers": {
    "archivist-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.myarchivist.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "archivist-ai": {
      "url": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "archivist-ai": {
      "serverUrl": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

Available Tools

Read tools are non-destructive and idempotent. Write tools follow standard REST semantics — deletes are destructive and idempotent; PATCH is non-idempotent; PUT is idempotent. Every read tool that returns text-carrying descriptions (Character, Faction, Location, Item, Moment, Beat, Session, Journal) accepts an optional with_links parameter — see Wikilinks below for why you almost always want to pass with_links: true before editing.

Campaign delete, session delete, product-view-only endpoints (beat reorder/batch-edit, campaign settings, cast/member management), multipart recording uploads, and AI image generation are intentionally not exposed.

OAuth scopes and write access

OAuth clients that connect via https://app.myarchivist.ai request scopes at authorization time. Every write tool (create/update/delete + image upload) additionally requires the agent_write scope on the caller's token.

The MCP mirrors the API's enforcement in tools/list: agent clients without agent_write see only the read tools, and receive a "tool not found" JSON-RPC error if they attempt to call a write tool anyway. API-key credentials and non-agent OAuth clients bypass this filter — the API is the authoritative gate for them and all tools remain visible.

Existing OAuth clients that connected before agent_write was advertised need to re-authorize to receive a token with the new scope.

Campaigns

Sessions

Story Structure

World Building

Quests

Journals

Relationships

Images

Wikilinks

Descriptions, summaries, moment content, and journal bodies in Archivist AI can contain [[Target Name|Optional Alias]] markup that resolves to real records. Every write tool that touches a text field carrying wikilinks has to follow a small protocol to avoid destroying existing links.

The one rule you must follow

Always read with with_links: true before writing. Every Get/List tool for Character, Faction, Location, Item, Moment, Beat, Session, and Journal accepts this parameter. The API defaults to stripping wikilinks so that read consumers get clean prose, which means a naive read/modify/write cycle will erase every [[…]] on the source record. Passing with_links: true returns the text with brackets intact so you can preserve them on write.

Per-record contract

Renaming and repointing

• Rename an alias: edit inside the brackets. [[Alice|Al]] → [[Alice|Ali]].
• Repoint at a different target: change the visible target name. [[Alice]] → [[Alicia]].
• Remove a link: unbracket the alias in the text (auto-resolve) or call delete_link (explicit).
• Campaign-wide rename or repoint for a compendium target: use bulk_link_maintenance with operation: "update", new_alias, and/or new_target_id. The API rewrites every referring text field in a background webhook and returns a task_id.

Images

Entity images can be added to Characters, Factions, Locations, Items, Moments, Sessions, and the Campaign itself via direct upload. The MCP server does not expose an AI image generation tool — image generation remains a product feature in the Archivist AI app and a REST endpoint on the API.

Direct upload (two-step)

For images the user already has on disk or in memory, use the presigned-URL flow:

1. Call init_image_upload with campaign_id, entity_type, entity_id, file_name, and content_type (must be image/*). You receive object_key, upload_url, public_url, and expires_in_seconds.
2. Your client (or a human collaborator) issues an HTTP PUT to upload_url with the raw image bytes and the same Content-Type header before the URL expires. This step happens outside the MCP transport.
3. Call complete_image_upload with object_key, entity_type, entity_id, and attach (defaults to true). The API validates the upload, runs NSFW moderation, and — when attach is true — sets the entity's image field to the moderated public_url.

Agents that cannot make arbitrary HTTP PUTs should hand the PUT step off to a human between step 1 and step 3.

Removal

delete_entity_image removes an image within a campaign in one of two modes:

• By entity: pass entity_type + entity_id. The API detaches the image from the record AND deletes the underlying object.
• By URL: pass a managed image_url (e.g. from a previous init_image_upload response). Deletes just the object.