Archivist AI

Archivist AI MCP Server

[MIT License] [Treeware] [Larabelles]

[GitHub PHPunit Status] [GitHub PHPStan Status] [GitHub Pint Status] [GitHub PHPMND Status]

[Discord] [Smithery] [Glama] [mcp.so]

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.1 && git push origin v3.0.1).

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.

{  "mcpServers": {    "archivist-ai": {      "command": "npx",      "args": [        "-y",        "mcp-remote",        "https://mcp.myarchivist.ai/mcp",        "--header",        "X-API-Key:${ARCHIVIST_API_KEY}"      ],      "env": {        "ARCHIVIST_API_KEY": "YOUR_API_KEY"      }    }  }}

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "archivist-ai": {      "type": "remote",      "url": "https://mcp.myarchivist.ai/mcp"    }  }}

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "archivist-ai": {      "type": "remote",      "url": "https://mcp.myarchivist.ai/mcp",      "oauth": false,      "headers": {        "X-API-Key": "{env:ARCHIVIST_API_KEY}"      }    }  }}

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

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

Example Prompts

• "List my campaigns, then summarize the most recent session of my Curse of Strahd campaign."
• "Create a new NPC named Captain Mirelle Voss, a smuggler who works for the Silver Hand faction, and link her to the Port of Dusk location."
• "Add a quest called 'Recover the Moonstone' to my campaign, then list all open quests and the characters involved."

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

Highlights

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.

Troubleshooting

• Authentication fails or tools return 401: reconnect the server and complete the OAuth sign-in again, or check that your API key is current in app.myarchivist.ai.
• Write tools are missing (agent OAuth clients only): write tools are hidden from agent OAuth clients that lack the agent_write scope. Reconnect and approve write access. API keys and non-agent OAuth clients always see all tools; see OAuth scopes and write access.
• Claude Desktop does not connect: it needs the mcp-remote proxy and Node.js; restart Claude Desktop after editing its config.
• Wikilinks disappear after an edit: read the record with with_links: true before updating it. See Wikilinks.

Privacy and Support

• Privacy policy: https://www.myarchivist.ai/privacy
• Support and security contact: [email protected]
• Community: Discord