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 v3.0.0 && git push origin v3.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):
{
"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:
{
"mcpServers": {
"archivist-ai": {
"url": "https://mcp.myarchivist.ai/mcp"
}
}
}
Windsurf
Add to your MCP configuration:
{
"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.
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, notes, type, public, image). 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.