___
/ __|_ __ _____ ___ _ __ _ __  ___ __ _
\__ \ V  V / -_) -_) '_ \ '_ \/ -_) _` |
|___/\_/\_/\___\___| .__/ .__/\___\__,_|
                   |_|  |_|

Sweeppea MCP Server

Model Context Protocol for Sweepstakes Management

How It Works

The Sweeppea MCP Server is a secure bridge between AI assistants and the Sweeppea API. It translates natural language interactions into structured API calls, giving your AI assistant full access to sweepstakes management — participants, official rules, winners, calendars, billing, and more.

Your AI Assistant  →  MCP (Model Context Protocol)  →  Sweeppea MCP Server  →  Sweeppea API v3

No local setup required — just point your MCP client to the endpoint and authenticate.

Authentication & Pricing

This MCP server requires a Sweeppea API Key tied to an active subscription.

Running sweepstakes in the United States and/or Canada is legally complex. Each state has its own regulations — registration requirements, bonding thresholds, void-where-prohibited rules, prize disclosure laws, and official rules that must comply with federal and state-level consumer protection statutes. Getting any of this wrong exposes sponsors to real legal liability.

Sweeppea handles that complexity for you and much more. The platform generates legally compliant official rules, manages multi-state eligibility, enforces entry limits, and provides an auditable record of every participant and winner draw. The API Key you use to connect isn't just authentication — it's your access to a system built specifically to keep sweepstakes legally defensible.

To get started:

1. Create an account at www.sweeppea.com

2. Choose a plan that fits your needs

3. Get your API Key from the API dashboard

4. Connect your MCP client using the configuration guides below

Documentation:

• MCP Server docs: mcpdocs.sweeppea.com
• API documentation: apidocs.sweeppea.com

Server-side Validations

The server enforces business and legal rules before a tool executes. If a call violates a rule, the tool is rejected and never reaches the Sweeppea API — no resources are created.

Two layers run on every `tools/call`:

• Hardcoded legal guardrails (inviolable): illegal lottery without AMOE, COPPA (minimum age below 13), and alcohol age gate.
• Dynamic declarative rules (editable by Sweeppea): additional checks on `create_sweepstakes`, `update_entry_settings`, `create_rules_wizard`, `create_note`, `create_ticket`, and `add_participant`.

A rejection returns a structured payload so your AI assistant can recover:

{
  "blocked_by": "server_validation",
  "error_code": "ALCOHOL_AGE_GATE_REQUIRED",
  "error_message": "Alcohol-related sweepstakes require an age gate of 21+.",
  "rule_id": "age_gate_must_be_21_when_active_v1"
}

`rule_id` is only present for dynamic rules. The AI assistant can read these fields and adjust the arguments before retrying.

Quick Start

Using Claude Code CLI:

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

See Platform Setup for Claude Desktop, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and more.

Available Tools (83)

Account Tools (4)

Entry Page Tools (3)

Sweepstakes Tools (7)

Participant Tools (6)

Group Tools (4)

Notes Tools (5)

Calendar Tools (5)

Rules Tools (5)

Billing & Wallet Tools (4)

Support Tickets Tools (7)

Winners Tools (5)

To-Do Tools (4)

Files Tools (5)

Invoice Tools (5)

> Requires the Invoices module enabled on the account — disabled by default. The API returns `403 "module is not enabled"` until Sweeppea activates it; contact support to request access.

Survey Tools (7)

> Requires the Surveys module enabled on the account — disabled by default. The API returns `403 "module is not enabled"` until Sweeppea activates it; contact support to request access.

Documentation Tools (1)

Utilities Tools (5)

Testing Tools (1)

Usage Examples

Initialize connection:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "client"}
    }
  }'

Add a participant:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "MCP-Session-Id: uuid-xxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "add_participant",
      "arguments": {
        "sweepstakes_token": "xxx-xxx-xxx",
        "email": "user@example.com",
        "fields": {"First_Name": "John", "Last_Name": "Doe"}
      }
    }
  }'

Platform Setup

Claude Code (CLI)

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

Claude Desktop / Cowork

Config file location:

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
• Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Requires Node.js installed.

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header", "Authorization: Bearer YOUR_API_KEY",
        "--header", "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)

1. Create or edit the config file with the JSON below

2. Replace `YOUR_API_KEY` with your Sweeppea API Key

3. Restart Cursor

4. Go to Settings > Tools & MCP

5. Enable the sweeppea server with the toggle switch

{
  "mcpServers": {
    "sweeppea": {
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Windsurf

`~/.codeium/windsurf/mcp_config.json` (global)

1. Create or edit the config file with the JSON below

2. Replace `YOUR_API_KEY` with your Sweeppea API Key

3. Go to Settings > Cascade > MCP Servers

4. Verify that sweeppea appears and is enabled

{
  "mcpServers": {
    "sweeppea": {
      "serverUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

GitHub Copilot (VS Code)

`.vscode/mcp.json` (workspace) or User Settings

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sweeppea-api-key",
      "description": "Sweeppea API Key",
      "password": true
    }
  ],
  "servers": {
    "sweeppea": {
      "type": "http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer ${input:sweeppea-api-key}",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Gemini CLI

`~/.gemini/settings.json` (global) or `.gemini/settings.json` (project)

{
  "mcpServers": {
    "sweeppea": {
      "httpUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Agent Zero

Open-source AI agent framework with MCP support.

1. Go to Settings > MCP/A2A > MCP Servers

2. Add the JSON configuration below

3. Replace `YOUR_API_KEY` with your Sweeppea API Key

4. Click Save

{
  "mcpServers": {
    "sweeppea": {
      "description": "Sweeppea - Sweepstakes Management API",
      "type": "streamable-http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Antigravity by Google

`~/.gemini/antigravity/mcp_config.json` (global)

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY",
        "--header",
        "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Protocol

License

MIT License - see LICENSE file for details.

(c) Sweeppea | All rights reserved