MCP Reference All docs

Getting Started

Your Players

All documentation

Chapter V · Section 2

Grimoire MCP Reference

What a connection can do, player access, switching and revoking, every tool Grimoire exposes, and troubleshooting.

This is the reference for Grimoire's MCP server: what a connection can do, how player access works, and every tool your AI app can call. To set up Claude, ChatGPT, Claude Code, Cursor, or another app, start with Connect to AI.

What a connection can do

  • Read everything about the single campaign you picked: NPCs, locations, factions, items, lore, quests, sessions, relationships, the Campaign Bible, the wiki, and open story threads.
  • Create and update on your behalf if you are the Gamemaster ("Create an NPC named Thrain, a dwarven weaponsmith based in Millbrook").
  • Respect visibility rules. GM Secret content stays GM-only. Player connections cannot read secrets or modify anything.
  • Stay within one campaign. A connection is bound to the campaign you approved on the consent screen. Your AI app cannot see your other campaigns through the same connection.

Player access

Your players can connect their own AI app to the campaign, but only if you allow it, and only ever read-only:

  1. As the GM, open Knowledge → MCP & AI → Player access and turn the toggle on. It is off by default.
  2. Optionally write a short guidance note for your players' AI assistants (house expectations, spoiler etiquette). It is guidance, not a lock; the hard limits below are enforced by the server regardless.
  3. Players then add the same connector URL, and your campaign appears under Campaigns you play in on their consent screen.

What a player connection can never do, no matter what the AI asks for:

  • Read anything marked GM Secret, session prep, or another player's wiki
  • See more of the world than the portal preset reveals
  • Create, edit, or delete anything

Player connections never receive the Campaign Bible through any tool. Only Bible blocks you mark Common Knowledge are meant for players, and a player-facing Bible view is planned.

Turning the toggle off, or removing the player from the campaign, cuts their AI access immediately, not when a token happens to expire. Every AI call, yours and theirs, lands in the activity log under Knowledge → MCP & AI → Audit Log, labeled by who made it.

The Campaign Bible and your AI

The Campaign Bible is GM Secret by default. When your AI writes to it, new blocks stay GM Secret unless you tell it a block is safe for players, such as how magic works or everyday life. Mark those blocks Common Knowledge from the block menu.

Switching campaigns

A connection is bound to a single campaign so your AI app only sees what you explicitly granted. To point it at a different campaign, remove the connector and add it again, picking the new campaign on the consent screen. You can also keep two connections side by side (add the URL twice, pick a different campaign each time).

Revoking access

  1. Remove the Grimoire connector in your AI app's settings.
  2. For players, turn off Player access or remove the player from the campaign, which cuts access immediately.
  3. Email grimoire@ttrpg.bot if you think access leaked and we revoke everything tied to your account.

What your AI actually sees

When you grant access, your AI app does not download a copy of your campaign. It calls Grimoire each time it needs something; the data lives on Grimoire's servers, and the app sees only the specific entity, page, or search result it asked for in the moment. More in our Privacy Policy.

Tool inventory

Grimoire exposes 52 tools. Read tools work for every connection; write tools work only for Gamemaster connections.

Entities

  • Read: search_campaign · get_entity · list_entities · get_field_options · get_entity_schema · get_tag_options
  • Write: create_entity · update_entity · delete_entity · batch_create_entities

Relationships

  • Read: get_relationships
  • Write: add_relationship · delete_relationship

Graphs and campaign knowledge

  • Read: get_constitution · get_entity_catalog · get_campaign_context · get_knowledge_graph · list_entity_graphs · get_entity_graph · get_narrative_state
  • Write: add_to_entity_graph · create_entity_graph_edge · toggle_graph_attention

World Foundations

  • Write: create_foundation_node · update_foundation_node · delete_foundation_node · create_foundation_edge · delete_foundation_edge · update_world_foundations

Open threads

  • Read: get_open_threads · get_thread_progressions
  • Write: create_open_thread · update_open_thread · resolve_open_thread · unresolve_open_thread · add_thread_progression

Session observations

  • Write: create_session_observation · update_session_observation · delete_session_observation

Wiki and Campaign Bible

  • Read: get_wiki_page · get_wiki_tree · get_campaign_bible · search_wiki
  • Write: create_wiki_page · create_wiki_block · update_wiki_block · move_wiki_block · delete_wiki_block · batch_create_wiki_blocks · batch_reorder_wiki_blocks · update_campaign_bible

Session

  • Read: current_campaign

Wiki tables round-trip as plain markdown grids, and entity and page links work inside cells.

Your AI decides which tool to call; you never need this list.

Troubleshooting

"I don't see a Connect button after adding the URL."

Make sure you pasted exactly https://api.ttrpg.bot/mcp with no trailing slash or query string. The connector should appear in your AI app's connector list with a sign-in or connect button next to it.

For Your campaigns: the account you signed in with does not run any campaigns yet. For Campaigns you play in: the GM has not enabled Player access for that campaign; ask them to flip it on under Knowledge → MCP & AI → Player access.

"My AI says it doesn't know about something I know is in the campaign."

Three common causes: the connector's tools are turned off in your AI app's tool permissions; the content is GM Secret and you are connected as a player; or (for players) the portal preset simply has not revealed it yet.

"Connection expired" / my AI app asks me to reconnect.

Tokens are short-lived and refresh automatically. If a refresh fails, reconnect and approve again. For players: if reconnecting fails outright, your GM may have turned Player access off.

"My app asks for an API key or token."

Grimoire connects with sign-in only. Look for an OAuth or "sign in" option; if your app has none, it cannot connect yet. See Connect to AI.

"ChatGPT finds things but will not create or edit."

That is ChatGPT's plan limit on custom connectors, not a Grimoire setting. See ChatGPT status.

Esc to close