🚀 Deployment Guide

Table of contents

1. Quick Start
   1. Step 1: Deploy GitHub Pages (Data Layer)
   2. Step 2: Deploy Cloudflare Worker (Server Layer)
   3. Step 3: Configure Custom Domain Route
   4. Step 4: Test the Server
   5. Step 5: Configure Your MCP Client
2. Verification Checklist
3. Troubleshooting
   1. “Server does not support streaming”
   2. “Failed to fetch data”
   3. CORS / Origin issues
   4. Worker not responding
   5. Tools not working
4. Local Development
   1. Test Worker Locally
5. Environment Variables
   1. Test GitHub Pages Locally
6. Cost Breakdown
   1. GitHub Pages
   2. Cloudflare Workers
7. Next Steps

---

Quick Start

Follow these steps to deploy your TTRPG MCP Server:

Step 1: Deploy GitHub Pages (Data Layer)

# Commit and push your changes
git add .
git commit -m "Add Cloudflare Worker MCP implementation"
git push origin main

GitHub Actions will automatically deploy to: https://ttrpg-mcp.tedt.org/

Step 2: Deploy Cloudflare Worker (Server Layer)

# Navigate to worker directory
cd cloudflare-mcp-server

# Install dependencies
npm install

# Login to Cloudflare (if not already)
npx wrangler login

# Deploy the worker
npm run deploy

Step 3: Configure Custom Domain Route

1. Go to Cloudflare Dashboard
2. Navigate to Workers & Pages
3. Click on your worker (ttrpg-mcp-server)
4. Go to Settings → Triggers
5. Under Custom Domains, add route:
   • Route: ttrpg-mcp.tedt.org/mcp
   • Zone: tedt.org

Step 4: Test the Server

Test the MCP endpoint:

curl -X POST https://ttrpg-mcp.tedt.org/mcp \
  -H "Content-Type: application/json" \
  -d '[
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-11-25",
        "capabilities": {},
        "clientInfo": { "name": "curl", "version": "0.0.0" }
      }
    },
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/list"
    }
  ]'

You should see JSON responses (not SSE). GET /mcp returns 405.

Tip: you can also inspect deployment fingerprint headers:

curl -I https://ttrpg-mcp.tedt.org/mcp

Step 5: Configure Your MCP Client

Add to your MCP client config (e.g., Claude Desktop):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ttrpg-gm-tools": {
      "url": "https://ttrpg-mcp.tedt.org/mcp",
      "transport": {
        "type": "http"
      }
    }
  }
}

Restart your MCP client to load the new server.

Verification Checklist

• GitHub Pages deployed successfully
• Can access https://ttrpg-mcp.tedt.org/
• Can view data files at https://ttrpg-mcp.tedt.org/data/encounters.json
• Cloudflare Worker deployed successfully
• Custom domain route configured
• Can POST to https://ttrpg-mcp.tedt.org/mcp
• MCP client configuration updated
• Can use tools in MCP client

Troubleshooting

“Server does not support streaming”

This means your MCP client is trying to use SSE transport. Make sure:

• Transport type is set to "http" (not "sse")
• URL points to /mcp endpoint, not /mcp.json

“Failed to fetch data”

Check that:

• GitHub Pages is deployed and accessible
• Data files exist at https://ttrpg-mcp.tedt.org/data/*.json
• Cloudflare Worker can access GitHub Pages (check CORS)

CORS / Origin issues

If calling from a browser context, ensure ALLOWED_ORIGINS includes your page origin (comma-separated list). Requests without an Origin header are allowed (typical non-browser MCP clients).

Worker not responding

• Check Cloudflare Dashboard for worker logs
• Verify custom domain route is configured correctly
• Test worker directly: npx wrangler tail

Tools not working

• Check worker logs for errors
• Verify data files are correctly formatted JSON
• Test individual data files in browser

Local Development

Test Worker Locally

cd cloudflare-mcp-server
npm run dev

Then test against localhost:

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Environment Variables

These are configured in cloudflare-mcp-server/wrangler.toml (or via Cloudflare dashboard):

• DATA_BASE_URL (default: https://ttrpg-mcp.tedt.org/data)
• DATA_CACHE_TTL_SECONDS (default: 3600)
• ALLOWED_ORIGINS (default: https://ttrpg-mcp.tedt.org)

Test GitHub Pages Locally

# Requires Ruby 3.1+ for the `github-pages` gem
bundle install
bundle exec jekyll serve
# Visit http://localhost:4000/

Cost Breakdown

GitHub Pages

• Cost: FREE ✅
• Limits: 100GB bandwidth/month, 1GB repo size

Cloudflare Workers

• Free Tier: 100,000 requests/day ✅
• Paid Plan: $5/month for 10M requests/month

For personal use, both stay within free tiers! 🎉

Next Steps

1. ✅ Deploy everything
2. 🧪 Test with your MCP client
3. 🎨 Customize the data files
4. 📊 Monitor usage in Cloudflare Dashboard
5. 🚀 Share with other GMs!