🎲 Dice MCP Server

A Model Context Protocol (MCP) server that provides dice rolling and coin flipping functionality for AI assistants like Claude.

Table of Contents

• What is MCP?
• How MCP Communication Works
• Available Tools
• Prerequisites
• Installation
• Testing
• Usage Examples
• Project Structure
• Development Guide
• Best Practices
• Implementation Patterns
• Output Formatting Guidelines
• Troubleshooting
• Security Considerations
• License
• Acknowledgements

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external tools and data sources. Think of it as a universal adapter that lets Claude use custom tools you create.

MCP servers run in Docker containers, providing:

• Isolation — Secure sandboxed environment
• Portability — Works on any system with Docker
• Standardization — Consistent protocol across all tools

How MCP Communication Works

MCP uses JSON-RPC 2.0 over stdio (standard input/output). Communication happens through a structured conversation between the client (Claude Desktop) and your server.

The 3-Step Handshake

Before any tools can be used, the client and server must complete an initialization handshake:

Step 1: Initialize (Client → Server)

{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":0}

"Hey server, I'm a client. Here's my protocol version and capabilities."

The server responds with its own capabilities and version info.

Step 2: Initialized Notification (Client → Server)

{"jsonrpc":"2.0","method":"notifications/initialized"}

"Got it! We're connected and ready to work."

Step 3: List Tools (Client → Server)

{"jsonrpc":"2.0","method":"tools/list","id":1}

"What tools do you have available?"

The server responds with all available tools, their parameters, and descriptions.

Visual Flow

┌──────────────────┐                    ┌──────────────────┐
│  Claude Desktop  │                    │  Your MCP Server │
│    (Client)      │                    │  (dice-mcp)      │
└────────┬─────────┘                    └────────┬─────────┘
         │                                       │
         │  1. initialize                        │
         │──────────────────────────────────────>│
         │                                       │
         │  Response: capabilities               │
         │<──────────────────────────────────────│
         │                                       │
         │  2. notifications/initialized         │
         │──────────────────────────────────────>│
         │                                       │
         │  3. tools/list                        │
         │──────────────────────────────────────>│
         │                                       │
         │  Response: [roll_dice, roll_multiple, │
         │            coin_flip]                 │
         │<──────────────────────────────────────│
         │                                       │
         │  4. tools/call (when you ask Claude)  │
         │──────────────────────────────────────>│
         │                                       │
         │  Response: "🎲 Rolled d20: 17"        │
         │<──────────────────────────────────────│

Why Docker + stdio?

Claude Desktop handles all of this automatically — you just say "roll a d20" and it manages the JSON-RPC behind the scenes!

Available Tools

Common Dice Notation

Prerequisites

• Docker Desktop with MCP Toolkit enabled
• Docker MCP CLI plugin (docker mcp command)

Installation

Step 1: Save the Files

# Create project directory
mkdir dice-mcp-server
cd dice-mcp-server

# Save these files in the directory:
# - Dockerfile
# - requirements.txt
# - dice_server.py
# - README.md
# - CLAUDE.md
# - ACKNOWLEDGEMENTS.md

Step 2: Build Docker Image

docker build -t dice-mcp-server .

Step 3: Create Custom Catalog

# Create catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs

# Create or edit custom.yaml
nano ~/.docker/mcp/catalogs/custom.yaml

Add this content to custom.yaml:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  dice:
    description: "Roll dice and flip coins with configurable options"
    title: "Dice Roller"
    type: server
    dateAdded: "2025-01-09T00:00:00Z"
    image: dice-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: roll_dice
      - name: roll_multiple
      - name: coin_flip
    metadata:
      category: productivity
      tags:
        - dice
        - random
        - games
      license: MIT
      owner: local

Nano Save Tips:

• Ctrl + O → Save
• Enter → Confirm filename
• Ctrl + X → Exit

Step 4: Update Registry

nano ~/.docker/mcp/registry.yaml

Add this entry under the existing registry: key:

registry:
  # ... existing servers ...
  dice:
    ref: ""

Step 5: Configure Claude Desktop

Find your Claude Desktop config file:

Ensure your config includes the custom catalog:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "[YOUR_HOME]/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

Replace [YOUR_HOME] with your home directory path:

• macOS: /Users/your_username
• Windows: C:\\Users\\your_username
• Linux: /home/your_username

Note: JSON does not support comments. Remove any // comments if present.

Step 6: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Start Claude Desktop again
3. Your dice tools should now appear!

Testing

Verify Docker Image

docker images | grep dice

Test MCP Protocol

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":0}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker run -i --rm dice-mcp-server

Expected output includes your three tools: roll_dice, roll_multiple, and coin_flip.

Verify Server in Docker MCP

docker mcp server list

Test in Claude Desktop

Just ask Claude:

• "Roll a dice"
• "Roll a d20"
• "Roll 4d6"
• "Flip a coin"

Usage Examples

Once installed, you can ask Claude things like:

Project Structure

dice-mcp-server/
├── Dockerfile           # Docker container configuration
├── requirements.txt     # Python dependencies
├── dice_server.py       # Main MCP server code
├── README.md            # This file
├── CLAUDE.md            # Implementation guidelines
└── ACKNOWLEDGEMENTS.md  # Credits and thanks

Development Guide

Adding New Tools

1. Add a new function to dice_server.py with the @mcp.tool() decorator
2. Use single-line docstrings only
3. Default parameters to empty strings (param: str = "")
4. Always return a formatted string
5. Update custom.yaml with the new tool name
6. Rebuild: docker build -t dice-mcp-server .

Local Testing Without Docker

pip install "mcp[cli]>=1.2.0"
python dice_server.py

Testing MCP Protocol Locally

# Set environment variables for testing
export SOME_VAR="test-value"

# Run directly
python dice_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python dice_server.py

Best Practices

Critical Rules for MCP Server Development

These rules prevent common errors that break Claude Desktop integration:

Code Generation Checklist

Before deploying your MCP server, verify:

• No @mcp.prompt() decorators used
• No prompt parameter in FastMCP()
• No complex type hints
• ALL tool docstrings are SINGLE-LINE only
• ALL parameters default to empty strings ("") not None
• All tools return strings
• Check for empty strings with .strip() not just truthiness
• Error handling in every tool
• Security handled via Docker secrets (if needed)
• Catalog includes version: 2, name, displayName, and registry wrapper
• Registry entries are under registry: key with ref: ""
• Date format is ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
• Claude config JSON has no comments

Implementation Patterns

✅ Correct Tool Implementation

@mcp.tool()
async def fetch_data(endpoint: str = "", limit: str = "10") -> str:
    """Fetch data from API endpoint with optional limit."""
    # Check for empty strings, not just truthiness
    if not endpoint.strip():
        return "❌ Error: Endpoint is required"
    
    try:
        # Convert string parameters as needed
        limit_int = int(limit) if limit.strip() else 10
        # Implementation
        return f"✅ Fetched {limit_int} items"
    except ValueError:
        return f"❌ Error: Invalid limit value: {limit}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

❌ Incorrect Tool Implementation

# DON'T DO THIS:
@mcp.tool()
async def bad_example(
    endpoint: Optional[str] = None,  # ❌ Optional type hint
    limit: int = 10                   # ❌ Non-string parameter
) -> dict:                            # ❌ Non-string return type
    """
    This is a multi-line docstring.   # ❌ Multi-line docstring
    It will cause gateway panic errors.
    """
    return {"result": "data"}          # ❌ Returns dict, not string

API Integration Pattern

async with httpx.AsyncClient() as client:
    try:
        response = await client.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        data = response.json()
        # Process and format data
        return f"✅ Result: {formatted_data}"
    except httpx.HTTPStatusError as e:
        return f"❌ API Error: {e.response.status_code}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

System Command Pattern

import subprocess

try:
    result = subprocess.run(
        command,
        capture_output=True,
        text=True,
        timeout=10,
        shell=True  # Only if needed
    )
    if result.returncode == 0:
        return f"✅ Output:\n{result.stdout}"
    else:
        return f"❌ Error:\n{result.stderr}"
except subprocess.TimeoutExpired:
    return "⏱️ Command timed out"

File Operations Pattern

try:
    with open(filename, 'r') as f:
        content = f.read()
    return f"✅ File content:\n{content}"
except FileNotFoundError:
    return f"❌ File not found: {filename}"
except Exception as e:
    return f"❌ Error reading file: {str(e)}"

Output Formatting Guidelines

Use emojis for visual clarity in your tool responses:

Formatting Multi-line Output

return f"""📊 Results:
- Field 1: {value1}
- Field 2: {value2}
- Field 3: {value3}

Summary: {summary}"""

Troubleshooting

Tools Not Appearing in Claude

1. Verify Docker image built successfully: docker images | grep dice
2. Check that custom.yaml is properly formatted (YAML is whitespace-sensitive)
3. Ensure Claude Desktop config includes --catalog=/mcp/catalogs/custom.yaml
4. Verify registry entry is under the registry: key, not at root level
5. Restart Claude Desktop completely (quit and reopen)

"Request before initialization" Error

This is expected when testing with a simple echo command. The MCP protocol requires the full handshake sequence. Claude Desktop handles this automatically.

Gateway Panic Errors

Usually caused by:

• Multi-line docstrings (use single-line only)
• @mcp.prompt() decorators (remove them)
• prompt parameter in FastMCP() (remove it)

Container Won't Start

Check Docker logs:

docker logs $(docker ps -lq)

Authentication Errors (for API-based servers)

• Verify secrets with docker mcp secret list
• Ensure secret names match in code and catalog
• Check environment variable names match

Security Considerations

License

MIT License

Acknowledgements

See ACKNOWLEDGEMENTS.md for credits and thanks.

Resources

• MCP Protocol Specification
• Docker MCP Toolkit Documentation
• FastMCP Python Library
• NetworkChuck's Docker MCP Tutorial