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, key moments, hero awards, quotes, spotlights, and more.

Quick Start

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

Discord tools live on a sibling host: https://discord.myarchivist.ai/mcp. That is a separate MCP resource (OAuth + your recording bot) and does not replace campaign tools here.

Claude Desktop

Claude Desktop requires the mcp-remote proxy (Node.js must be installed).

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

config.json

{
  "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"
      }
    }
  }
}

Replace YOUR_API_KEY with your Archivist AI API key from app.myarchivist.ai. Restart Claude Desktop after saving.

Cursor

Add to .cursor/mcp.json in your project:

config.json

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

Windsurf

Add to your MCP configuration:

config.json

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

ChatGPT

Archivist AI is available as a ChatGPT plugin. Search for "Archivist AI" in the ChatGPT plugin store.

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

Tool	Description
`list_campaigns`	List your campaigns. Returns a paginated list.
`get_campaign`	Get a specific campaign by ID.
`get_campaign_stats`	Get statistics for a campaign: character count, session count, and more.
`create_campaign`	Create a new campaign. Subject to the account's subscription-tier campaign limit.
`update_campaign`	Partially update campaign metadata (title, description, tones, public/mature flags).

Sessions

Tool	Description
`list_sessions`	List game sessions. Filter by session type or public-only.
`get_session`	Get a session by ID. Optionally include related beats and moments.
`get_session_cast_analysis`	Get cast analysis: talk-share breakdown and core session metrics.
`get_session_transcript`	Get the cleaned transcript for a game session, including utterances, full text, and aggregate stats.
`get_session_handout`	Get the generated session handout for a game session, including summary, outlines, spotlights, and notable moments.
`patch_session`	Partial update (title, session_date, summary, image). Explicit-link contract for wikilinks.
`update_session`	Full update (PUT). Explicit-link contract for wikilinks.

Story Structure

Tool	Description
`list_beats`	List beats ordered by index. Beats represent story moments (major, minor, step).
`get_beat`	Get a specific beat by ID.
`create_beat`	Create a beat. Explicit-link contract for wikilinks.
`update_beat`	Partially update a beat.
`delete_beat`	Delete a beat (child beats have parent_id cleared).
`list_moments`	List Key Moments (Moments) in a campaign or session. Filter by label, categories (typically `key-moment`), or kind. Includes image and presentation metadata.
`get_moment`	Get a Key Moment by ID, including image URL, categories, kind, and metadata.
`create_moment`	Create a Key Moment attached to a session. Set `categories=["key-moment"]` for a Key Moment card. Explicit-link contract for wikilinks.
`update_moment`	Partially update a Key Moment, including image and merged presentation metadata.
`delete_moment`	Delete a Key Moment.

Highlights

Tool	Description
`list_hero_awards`	List hero awards in a campaign or session.
`get_hero_award`	Get a hero award by ID.
`create_hero_award`	Create a hero award attached to a session.
`update_hero_award`	Partially update a hero award.
`delete_hero_award`	Delete a hero award.
`list_quotes`	List memorable session quotes in a campaign or session.
`get_quote`	Get a quote by ID.
`create_quote`	Create a quote attached to a session (creates a recap pipeline if needed).
`update_quote`	Partially update a quote.
`delete_quote`	Delete a quote.
`list_spotlights`	List recap spotlights (GEMS cards, not session-handout spotlights).
`get_spotlight`	Get a recap spotlight by ID.
`create_spotlight`	Create a recap spotlight attached to a session.
`update_spotlight`	Partially update a recap spotlight.
`delete_spotlight`	Delete a recap spotlight.

World Building

Tool	Description
`list_characters`	List characters in a campaign. Filter by name, type (PC/NPC), or approval status.
`get_character`	Get a character by ID including aliases, backstory, and speaker linkage.
`create_character`	Create a character. Description/backstory wikilinks auto-resolve.
`update_character`	Partially update a character. Read with `with_links: true` before editing description/backstory.
`delete_character`	Delete a character. API unbrackets all inbound `[[alias]]` references automatically.
`list_factions`	List factions. Factions represent guilds, organisations, or other groups.
`get_faction`	Get a specific faction by ID.
`create_faction`	Create a faction. Description wikilinks auto-resolve.
`update_faction`	Partially update a faction. Read with `with_links: true` before editing.
`delete_faction`	Delete a faction.
`list_locations`	List locations. Locations can be nested (cities, taverns, dungeons, etc.).
`get_location`	Get a specific location by ID.
`create_location`	Create a location. Description wikilinks auto-resolve.
`update_location`	Partially update a location. Read with `with_links: true` before editing.
`delete_location`	Delete a location (child locations have parent_id cleared).
`list_items`	List items. Items include weapons, armour, artefacts, and other notable objects.
`get_item`	Get a specific item by ID.
`create_item`	Create an item. Description wikilinks auto-resolve.
`update_item`	Partially update an item. Read with `with_links: true` before editing.
`delete_item`	Delete an item.

Quests

Tool	Description
`list_quests`	List quests with pagination. Filter by status or category.
`get_quest`	Get a fully expanded quest: objectives, progress log, related entities, session provenance.
`create_quest`	Create a quest entry. Quests do not participate in the wikilinks system.
`update_quest`	Partially update a quest. Lists you send replace their corresponding lists on the record.
`delete_quest`	Delete a quest and its objectives / progress entries / related refs.

Journals

Tool	Description
`list_journals`	List journal entries. Content omitted from list; use get_journal for full content.
`get_journal`	Get a journal entry by ID including full content and permission level.
`create_journal`	Create a journal entry. Returns `{success, id}`.
`update_journal`	Update a journal entry (PUT). Returns `{success, id}`.
`delete_journal`	Delete a journal entry (embeddings are best-effort deleted).
`list_journal_folders`	List journal folders ordered by path and position for tree rendering.
`get_journal_folder`	Get a specific journal folder by ID.
`create_journal_folder`	Create a journal folder (owners/admins only; path must be unique per campaign).
`update_journal_folder`	Update a journal folder (PUT).
`delete_journal_folder`	Delete a folder; entries move to the campaign root.

Relationships

Tool	Description
`list_links`	List links between entities. Filter by source/target entity and relationship alias.
`create_link`	Create a Link row between two entities (upserts if `(from_type, from_id, alias)` collides).
`update_link`	Update an existing link's alias.
`delete_link`	Delete a single Link row (does not rewrite the source's text).
`bulk_link_maintenance`	Trigger campaign-wide link maintenance (add/remove/update) via webhook — requires an active subscription tier.

Images

Tool	Description
`get_image_usage`	Return the calling account's image quota for a campaign: `used`/`limit`, `tier`, `can_access`, and cycle window.
`init_image_upload`	Step 1 of direct upload: reserve an `object_key` and receive a presigned S3 PUT URL. The client then PUTs the raw image bytes to `upload_url` with the same `Content-Type`. Expires after `expires_in_seconds`.
`complete_image_upload`	Step 2 of direct upload: validate the uploaded object, run NSFW moderation, and (when `attach: true`) set the entity's `image` field to the moderated URL.
`delete_entity_image`	Remove an image. Provide `entity_type` + `entity_id` (detaches AND deletes the object) or `image_url` (deletes just the object).

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

Record type	Contract
Character, Faction, Location, Item, Character.backstory	Auto-resolve. On write, the API extracts `[[…]]` from your new text, matches each against records in the same campaign, and syncs the Link table (inserts new, updates changed, deletes removed). New `[[Alias]]` markup for a matchable target creates a Link automatically.
GameSession, Beat, Moment	Explicit-link only. The API strips `[[Alias]]` markup that does NOT already have a matching Link row for that source. To add a wikilink, first call `create_link` with the correct `from_type`/`from_id`, then include `[[Alias]]` in the text on your write.
Journal	Rendering-only. Stored `[[…]]` markup renders as links on read with `with_links: true` but writes do not auto-populate the Link table. Use `create_link` (`from_type=Journal`) if you want persistent link tracking.
Quest	No wikilinks. Quest text fields are stored verbatim. Relationships are modelled via the `related_*` list fields, not wikilinks.
Delete (any record)	The API automatically unbrackets all `[[alias]]` references to a deleted record across every referring text field. No manual cleanup is required.

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:

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