MCP Server

An MCP (Model Context Protocol) server exposing FlowDice’s dice engine as structured tools. Allows any MCP-compatible client to roll dice, manage favorites, and use templates programmatically.

Why

• AI-assisted TTRPG play: Claude or other assistants can roll real dice through FlowDice’s engine — cryptographically secure, same notation, actual randomness instead of hallucinated numbers
• VTT integration: Discord bots, virtual tabletops, and other tools can use FlowDice as their dice engine via MCP
• Template access: Structured tool calls for common roll patterns without needing to compose notation manually
• Shared engine: Same Ruby dice engine powers the web app, PWA, Hotwire Native shells, and MCP — one codebase, multiple interfaces

Proposed Tools

Core (Phase 1 candidate)

Tool	Input	Output
roll	Notation string	Total, individual dice, notation used
parse	Notation string	Human-readable explanation

Extended (Phase 2, alongside Template Library)

Tool	Input	Output
roll_flow	Flow notation, named param selections	Box 1 result + preloaded Box 2 notation
list_favorites	—	Array of saved favorites
roll_favorite	Favorite name, optional param overrides	Roll result
list_templates	—	Available templates
roll_template	Template name + parameter values	Roll result

Architecture

The MCP server is a thin layer over the same dice engine that powers the web UI. In Rails terms:

DiceEngine (core Ruby lib)
├── Web UI (Rails controllers + Stimulus)
├── API (JSON endpoints for native apps)
└── MCP Server (tool definitions + handlers)

The MCP server could be:

• A Rack middleware in the Rails app
• A standalone Ruby process sharing the engine gem
• A separate service for scaling independently

Example Interactions

Simple roll:

Client: roll("2d20kh+5")
Server: { total: 23, kept: [18], dropped: [7], modifier: 5, notation: "2d20kh+5" }

Flow with named params:

Client: roll_flow("(<adv>?2d20kh:d20)+4->(d8(<smite>?+2d8))(n20?c)+3", { adv: true, smite: true })
Server: {
  box1: { total: 24, natural: 20, notation: "2d20kh+4" },
  box2: { notation: "2d8+4d8+3", crit_applied: "normal", preloaded: true }
}

Template:

Client: roll_template("dnd5e_weapon_attack", { to_hit: 7, damage: "d8", modifier: 4, crit: "perkins" })
Server: { attack: { total: 27, natural: 20 }, damage: { notation: "8+d8+4", preloaded: true } }

Phase Placement

• Phase 1: Basic roll and parse tools if the engine is well-factored from the start
• Phase 2: Full tool suite alongside Template Library and Named Parameters
• The MCP server motivates clean engine separation early — if the dice engine is a standalone Ruby module/gem, MCP is trivial to add

Ecosystem Value

An open MCP dice server could become a standard tool for the TTRPG + AI community. Anyone building AI-powered TTRPG tools gets a real dice engine for free. This aligns with FlowDice’s philosophy of democratizing tools.

See also: Architecture, Template Library, Notation Spec, Flows