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

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.

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

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

Add to your MCP configuration:

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

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), and multipart recording uploads 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 generation and 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. Two flows are supported:

Server-side AI generation

Call generate_image with a campaign_id, a type (character, faction, location, item, or world), and optionally an entity_id (defaults to the campaign for type=world) and free-form user_input. The API rewrites the entity's stored description into a visual prompt, calls the configured provider, and returns a public URL.

Two things worth calling out:

1. The generated image is not automatically attached — set image on the entity via the matching update tool (e.g. update_character, update_faction) if you want to persist it on the record.
2. Generation consumes the account's per-cycle image quota. Call get_image_usage first if you need to reason about headroom, tier limits, or the current billing window. AI features are disabled on archived campaigns.

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 prefer generate_image or 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.