Archivist AI Agent Examples

Build AI agents powered by your TTRPG campaign data. This repository contains working examples, configuration files, and reference documentation for integrating Archivist AI with AI assistants and agent frameworks.

Archivist AI is a TTRPG campaign memory platform for game masters and players. It turns Discord sessions, uploaded audio, transcripts, and play-by-post content into structured campaign history -- characters, locations, factions, items, quests, session timelines, and more -- that can be searched, queried, and used by AI agents.

Quick Start

Connect via MCP (Model Context Protocol)

The Archivist MCP server gives AI assistants direct, read-only access to your campaign data. No SDK or API key wrangling required -- just point your client at the server.

MCP Server URL: https://mcp.myarchivist.ai/mcp Transport: Streamable HTTP Authentication: OAuth 2.0 (authorization code + PKCE) or Bearer token

Claude.ai (Connectors Directory)

Connect Archivist as a remote MCP connector in Claude on the web — no config file required.

1. Open Settings → Connectors in claude.ai
2. Add custom connector URL: https://mcp.myarchivist.ai/mcp
3. Complete OAuth sign-in with your Archivist account

Full guide: examples/claude-ai/README.md

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor

Add to your .cursor/mcp.json:

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

Windsurf

Add to your MCP configuration:

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

Examples

Example	Description	Language
Claude.ai Setup	Connect Archivist to Claude on the web via OAuth connector	Config
Claude Desktop Setup	Connect Archivist to Claude Desktop via MCP	Config
Cursor Setup	Connect Archivist to Cursor IDE via MCP	Config
Windsurf Setup	Connect Archivist to Windsurf IDE via MCP	Config
Session Recap Agent	Generate session recaps automatically	Python
NPC Recall Agent	Ask questions about campaign lore and NPCs	Python
GM Copilot	GM assistant with function calling + Archivist retrieval	Python
Session Recap (TypeScript)	Generate session recaps with AI SDK	TypeScript
Campaign Explorer	Interactive campaign Q&A agent	TypeScript

MCP Tools Reference

The Archivist MCP server exposes 27 read-only tools for accessing campaign data:

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.

Characters

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.

Sessions

Tool	Description
list_sessions	List game sessions in a campaign. 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 for a session: talk-share breakdown and core metrics.
get_session_handout	Get the generated session handout: summary, outlines, and spotlights.
get_session_transcript	Get the cleaned session transcript with utterances and aggregate stats.

Story Structure

Tool	Description
list_beats	List beats in a campaign, ordered by index. Beats represent story moments (major, minor, step).
get_beat	Get a specific beat by ID.
list_moments	List moments in a campaign or session. Moments capture memorable quotes and events.
get_moment	Get a specific moment by ID.

World Building

Tool	Description
list_factions	List factions in a campaign. Factions represent guilds, organisations, or other groups.
get_faction	Get a specific faction by ID.
list_locations	List locations in a campaign. Locations can be nested (cities, taverns, dungeons, etc.).
get_location	Get a specific location by ID.
list_items	List items in a campaign. Items include weapons, armour, artefacts, and other notable objects.
get_item	Get a specific item by ID.

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, and session provenance.

Journals

Tool	Description
list_journals	List journal entries in a campaign. Content omitted from list; use get_journal for full content.
get_journal	Get a journal entry by ID including full content and permission level.
list_journal_folders	List journal folders for a campaign, ordered by path and position for tree rendering.
get_journal_folder	Get a specific journal folder by ID.

Relationships

Tool	Description
list_links	List links between entities. Filter by source/target entity and relationship alias.

REST API

For direct API access without MCP, use the Archivist REST API:

• Base URL: https://api.myarchivist.ai
• Authentication: x-api-key header
• OpenAPI Spec: https://api.myarchivist.ai/openapi.json
• Developer Portal: developers.myarchivist.ai
• API Playground: developers.myarchivist.ai/playground

Get your API key from the Developer tab in your Archivist profile.

Available On

• Official MCP Registry — io.github.Astrotomic/archivist-ai
• Smithery
• Glama
• mcp.so

Connectors Directory (Anthropic)

Preparing for Claude's Connectors Directory? Start here:

• Anthropic submission guide
• Claude.ai setup
• Reviewer guide template
• Tool testing matrix
• Tools manifest for submission form

Verify live server metadata:

./scripts/verify-server-card.sh

Resources

• Archivist AI -- Product homepage
• Developer Portal -- API docs, playground, guides
• MCP Server Card -- Machine-readable server capabilities
• For AI Agents -- Structured guide for LLM tool selection
• MCP Tool Reference -- Complete tool documentation
• Anthropic Connectors Directory -- Submission checklist
• Privacy Policy -- Required for directory submission
• Discord -- Community and support

License

MIT