Looking for the product overview and connect flow? See the Archivist MCP landing page. This page covers setup, authentication, tools, and discovery metadata.

MCP Server

Connect AI assistants to persistent campaign memory using the Model Context Protocol. Archivist exposes structured read and write access to campaigns, sessions, characters, quests, journals, entity relationships, and entity images.

Claude.ai

Connect via Settings → Connectors.

Other Clients

Desktop, Cursor, and Windsurf setup.

Tools Reference

67 tools — read, write, and image operations.

Security & Annotations

OAuth scopes, write tools, and MCP hints.

Agent Examples

Working code and config files.

Overview

The Archivist AI MCP server gives AI assistants like Claude, ChatGPT, Cursor, and Windsurf direct access to persistent campaign memory. With 67 tools (28 read, 39 write), agents can browse campaigns, create and update entities, manage links, generate or upload images, and more without leaving the conversation.

Server URL

https://mcp.myarchivist.ai/mcp

Registry ID

io.github.Astrotomic/archivist-ai

Transport

Streamable HTTP

Authentication

OAuth 2.0 (PKCE) or Bearer token

Tools

67 tools (read + write + images)

Source

github.com/Astrotomic/mcp.myarchivist.ai

Claude.ai (Connectors)

Connect Archivist as a remote MCP connector in Claude on the web. This is the recommended path for Anthropic's Connectors Directory and everyday Claude users.

Open claude.ai → Settings → Connectors
Add custom connector URL: https://mcp.myarchivist.ai/mcp
Click Connect and sign in with your Archivist account (OAuth)
Start a new chat and ask about your campaign history

Full guide with example prompts: agent-examples / claude-ai · Submission checklist: Anthropic directory guide

Other Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "archivist-ai": {
      "type": "streamable-http",
      "url": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Cursor

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

{
  "mcpServers": {
    "archivist-ai": {
      "type": "streamable-http",
      "url": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

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

Authentication

The MCP server supports two authentication methods:

OAuth 2.0 (recommended for interactive clients)

Authorization code flow with PKCE. When you first use a tool, your MCP client will redirect you to sign in with your Archivist account. Supported scopes: profile, worlds_read, sessions_read, characters_read, and agent_write (mutating tools).

Bearer Token (for programmatic access)

Pass your Archivist API key as a Bearer token. Get your key from the Developer tab in your Archivist profile.

Available Tools

28 read tools plus 39 write tools (including five image tools). Write tools require the agent_write OAuth scope. Full parameter reference: agent-examples / mcp-tool-reference. Pass with_links: true on read tools before editing wikilink-bearing text.

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: character count, session count, and more.

Characters

Tool	Description
`list_characters`	List characters. Filter by name, type (PC/NPC), or approval status.
`get_character`	Get a character including aliases, backstory, and speaker linkage.

Sessions

Tool	Description
`list_sessions`	List game sessions. Filter by type or public-only.
`get_session`	Get a session with optional beats and moments.
`get_session_cast_analysis`	Get cast analysis: talk-share breakdown and metrics.
`get_session_handout`	Get generated session handout: summary, outlines, spotlights.
`get_session_transcript`	Get cleaned session transcript with utterances and stats.

Story Structure

Tool	Description
`list_beats`	List beats ordered by index (major, minor, step).
`get_beat`	Get a specific beat by ID.
`list_moments`	List moments: memorable quotes and events.
`get_moment`	Get a specific moment by ID.

World Building

Tool	Description
`list_factions`	List factions (guilds, organisations, groups).
`get_faction`	Get a specific faction by ID.
`list_locations`	List locations (nested: cities, taverns, dungeons).
`get_location`	Get a specific location by ID.
`list_items`	List items (weapons, armour, artefacts).
`get_item`	Get a specific item by ID.

Quests

Tool	Description
`list_quests`	List quests. Filter by status or category.
`get_quest`	Get expanded quest: objectives, progress, entities, provenance.

Journals

Tool	Description
`list_journals`	List journal entries (content omitted; use get_journal).
`get_journal`	Get journal entry with full content and permissions.
`list_journal_folders`	List journal folders for tree rendering.
`get_journal_folder`	Get a specific journal folder by ID.

Relationships

Tool	Description
`list_links`	List entity links. Filter by source/target and alias.

Write Tools

Create, update, and delete tools mirror the REST API. Campaign delete, session create/delete, beat reorder, campaign settings, cast/member management, and recording uploads are not exposed.

Category	Tools
Campaigns	`create_campaign`, `update_campaign`
Sessions	`patch_session`, `update_session`
Beats / Moments	`create_beat`, `update_beat`, `delete_beat`, `create_moment`, `update_moment`, `delete_moment`
Compendium	`create_`, `update_`, `delete_*` for characters, factions, locations, items
Quests / Journals	Full CRUD for quests, journal entries, and journal folders
Links	`create_link`, `update_link`, `delete_link`, `bulk_link_maintenance`

Image Tools

Tool	Description
`get_image_usage`	Check quota before generating.
`generate_image`	AI-generate from entity context; attach via update tool.
`init_image_upload`	Presigned upload step 1.
`complete_image_upload`	Validate, moderate, and attach (step 2).
`delete_entity_image`	Detach/delete by entity or URL.

Security & Tool Annotations

Archivist MCP is designed for safe assistant access: scoped OAuth, explicit tool annotations, and campaign-level permission checks on every write.

OAuth scopes

Interactive clients request read scopes for browsing and agent_write when mutating campaign data: profile, worlds_read, sessions_read, characters_read, and agent_write.

Revoke MCP access anytime from your Archivist profile under Connected services.

Tool annotations

All tools advertise MCP hints to clients and registries:

Read tools advertise readOnlyHint: true. Write and delete tools use appropriate destructive/idempotent hints. All tools use openWorldHint: false.

Bearer token access

For programmatic clients, pass an Archivist API key as a Bearer token. Treat keys like passwords and rotate them from the Developer tab if compromised.

Example Prompts

Once connected, try these prompts with your AI assistant:

“List my campaigns and show the stats for each one”
“Who are the main NPCs in my campaign? Give me a summary of each.”
“What happened in the last three sessions?”
“Show me all the quests that are currently in progress”
“What do we know about the Thieves' Guild faction?”
“Find all moments where a specific character was mentioned”
“Summarize the character arc for a PC across all sessions”

Discovery & Registries

Machine-Readable Endpoints

Server Card — capabilities and tool listing
MCP Discovery — discovery endpoint
OAuth Metadata — authorization server metadata

Available On

Official MCP Registry — canonical metadata for io.github.Astrotomic/archivist-ai
Smithery — MCP server registry
Glama — MCP connector directory
mcp.so — MCP server directory
Product landing page — connect flow and overview

MCP Server

Claude.ai

Other Clients

Tools Reference

Security & Annotations

Agent Examples

Overview

Claude.ai (Connectors)

Other Clients

Claude Desktop

Cursor

Windsurf

Authentication

Available Tools

Campaigns

Characters

Sessions

Story Structure

World Building

Quests

Journals

Relationships

Write Tools

Image Tools

Security & Tool Annotations

Example Prompts

Discovery & Registries

Resources

REST API Code Examples

API Changelog

Connectors Directory Guide

Agent Examples

REST API Reference

MCP Landing Page

OpenAPI Spec

Discord Community