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 access to campaigns, sessions, characters, quests, journals, and entity relationships.

Claude.ai

Connect via Settings → Connectors.

Other Clients

Desktop, Cursor, and Windsurf setup.

Tools Reference

27 read-only tools for campaign data.

Security & Annotations

OAuth scopes, read-only 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 27 read-only tools, agents can browse campaigns, look up characters, review session history, explore quest logs, 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

27 read-only, idempotent tools

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.

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

All 27 tools are read-only, non-destructive, and idempotent. Write operations are planned for v2.

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.

Security & Tool Annotations

Archivist MCP is designed for safe assistant access: scoped OAuth, read-only tools in v1, and explicit MCP tool annotations on every endpoint.

OAuth scopes

Interactive clients request only the scopes needed to read campaign data: profile, worlds_read, sessions_read, and characters_read.

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

Tool annotations

All tools advertise MCP hints to clients and registries:

readOnlyHint: true
destructiveHint: false
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

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