MCP Integration

Integrate RANDSUM with AI agents like Claude and ChatGPT using the Model Context Protocol (MCP) server.

What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI agents to interact with tools and services. RANDSUM provides an MCP server that exposes dice rolling capabilities to AI agents.

Installation

Install the MCP server globally or use it via npx:

Installing MCP Server

# Install globally
npm install -g @randsum/mcp

# Or use via npx (no installation needed)
npx @randsum/mcp

Configuration

Add the RANDSUM MCP server to your MCP client configuration:

Claude Desktop Configuration

{
  "mcpServers": {
    "randsum": {
      "command": "npx",
      "args": ["-y", "@randsum/mcp@latest"]
    }
  }
}

Configuration Location: Claude Desktop configuration is typically located at:
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\\Claude\\claude_desktop_config.json (Windows)

Available Tools

The RANDSUM MCP server provides the following tools:

  • roll - Execute dice rolls with full notation support
  • try-roll - Safe rolling without exceptions (returns Result type)
  • validate-notation - Validate and parse dice notation
  • analyze - Probability analysis of dice notation
  • game-roll - Roll dice for specific game systems
  • batch-roll - Roll multiple times in a batch
  • compare - Compare probability distributions
  • count-successes - Dice pool success counting
  • preset - Roll using preset configurations

Example Usage

Once configured, you can ask AI agents to roll dice:

AI Agent Interaction

User: "Roll 4d6 drop lowest for a D&D ability score"
AI: [Uses roll tool] "I rolled 4d6L: [4, 5, 3, 6]. 
    Dropped 3 (lowest). Total: 15 (4+5+6)."

User: "What's the probability distribution of 4d6L?"
AI: [Uses analyze tool] "4d6L has a mean of ~12.24..."

Available Prompts

The MCP server also provides prompts for common scenarios:

  • dnd-ability-scores - Generate D&D 5e ability scores
  • blades-action - Roll Blades in the Dark action
  • combat-round - Roll initiative and attacks
  • pbta-roll - Roll Powered by the Apocalypse move

Transport Modes

The MCP server supports multiple transport modes:

Transport Modes

# STDIO (default)
npx @randsum/mcp

# HTTP
npx @randsum/mcp --transport http

# Server-Sent Events
npx @randsum/mcp --transport sse --port 3001

Resources

The MCP server also provides documentation resources:

  • dice-notation-docs - Complete notation reference
  • error-reference - Error types and recovery
  • game-systems - Supported game systems overview

Next Steps