Sweeppea

 ___
/ __|_ __ _____ ___ _ __ _ __  ___ __ _
\__ \ 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), alcohol 21+ age gate, nicotine 21+ age gate and state exclusions, no nicotine products as prizes, and explicit confirmation for promotions aimed at minors.
• 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.

Irreversible tools — every delete_*, plus send_message, send_code, cancel_campaign, remove_suppression and unassign_code — require confirm: true and are rejected without it.

---

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 (109)

Account Tools (4)

Tool	Description
health_check	Verify connection to Sweeppea API and validate your API key
get_profile	Get user profile information for a Sweeppea account
get_business	Get business information including company details and address
get_plan	Get subscription plan details including pricing, limits and features

Entry Page Tools (3)

Tool	Description
get_entry_fields	Get all form fields for a sweepstakes entry page. Use before adding participants
get_entry_settings	Get all entry page settings: display, colors, compliance, confirmation, winners, age gate, AMOE, and more
update_entry_settings	Update 1-5 entry page settings per request. Supports 80+ configurable fields

Sweepstakes Tools (7)

Tool	Description
fetch_sweepstakes	List sweepstakes with pagination. Returns a summary with a computed lifecycle state (scheduled, running, ended)
create_sweepstakes	Create a new sweepstakes with type, handler, dates, and times
update_sweepstakes	Update an existing sweepstakes (name, dates, times)
clone_sweepstakes	Clone an existing sweepstakes with new parameters and dates
pause_sweepstakes	Pause a sweepstakes, setting it to inactive while preserving data
unpause_sweepstakes	Reactivate a paused sweepstakes to allow new entries
delete_sweepstakes	Permanently delete a sweepstakes and all associated data

Participant Tools (6)

Tool	Description
add_participant	Add a new participant to a sweepstakes with custom fields. Both email and phone are required
get_participant	Fetch a single participant by token, email, or phone number
fetch_participants	List participants with pagination (20/page), search, and date filters
count_participants	Get participant counts with optional filtering by type and date
update_bonus_entries	Update the bonus entries value for a participant in a sweepstakes
delete_participant	Permanently remove a participant from a sweepstakes

Group Tools (4)

Tool	Description
fetch_groups	Get all groups from a sweepstakes for participant segmentation
create_group	Create a new group within a sweepstakes
update_group	Update the name of an existing group in a sweepstakes
delete_group	Delete a group. Cannot delete primary, locked, or groups with participants

Notes Tools (5)

Tool	Description
fetch_notes	Get all notes, decrypted and in reverse chronological order
get_note	Fetch a single note by token. Content is automatically decrypted
create_note	Create a new note. Content is encrypted using AES-256-CBC
update_note	Update an existing note. Supports partial updates
delete_note	Permanently delete a note. This action cannot be undone

Calendar Tools (5)

Tool	Description
fetch_calendar_events	Get all calendar events with dates, times, and status
get_calendar_event	Get a single calendar event by its token with full details
create_calendar_event	Create a new calendar event with title, dates, and notifications
update_calendar_event	Update an existing calendar event. Cannot update to past dates
delete_calendar_event	Permanently delete a calendar event. Cannot be undone

Rules Tools (5)

Tool	Description
fetch_rules	Get all official rules including primary and secondary rules
create_rule	Create a new official rules document with HTML content
update_rule	Update an existing official rules document. Supports partial updates
delete_rule	Permanently delete an official rules document. Cannot be undone
create_rules_wizard	Generate official rules via 14-step wizard. Complete HTML rules server-side

Billing & Wallet Tools (4)

Tool	Description
fetch_wallet_transactions	Get all wallet transactions including credits, debits, and payments
fetch_billing_transactions	Get all billing transactions including invoices and amounts
fetch_billing_consumptions	Get monthly and yearly billing consumption totals
fetch_data_transfer	Get data transfer records for a specific sweepstakes with costs

Support Tickets Tools (7)

Tool	Description
fetch_open_tickets	Get open tickets with pagination, search, platform and priority filters
fetch_closed_tickets	Get closed tickets with pagination, search, platform and priority filters
get_ticket	Get full ticket details by case number including notes and files
create_ticket	Create a new support ticket with title, description, priority, assignee and platform
resolve_ticket	Close/resolve an open support ticket
update_ticket	Update an open support ticket. At least one field required
delete_ticket	Permanently delete an open support ticket. Cannot be undone

Winners Tools (5)

Tool	Description
fetch_winners	Get winners from a sweepstakes with pagination and search
draw_winners	Draw random winners from eligible participants
schedule_drawing	Schedule a future winner drawing for a sweepstakes
fetch_scheduled_drawings	Get all scheduled drawings for a sweepstakes
delete_scheduled_drawing	Delete a pending scheduled drawing. Only pending drawings can be deleted

To-Do Tools (4)

Tool	Description
fetch_todos	Get all To-Do items with pagination (20 per page), search, and advanced filters
create_todo	Create a new internal To-Do item
update_todo	Update an existing To-Do item. Supports partial updates
delete_todo	Permanently delete a To-Do item. This action cannot be undone

Files Tools (5)

Tool	Description
fetch_files	List all files in the user's Drive with storage usage, categories, and pagination
upload_file	Upload a file to the user's Drive. The file must be base64-encoded
get_file_url	Generate a short-lived presigned S3 URL to download or preview a file from the user's Drive
send_file	Send a file from the user's Drive as an email attachment
delete_file	Permanently delete a file from the user's Drive

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.

Tool	Description
create_invoice	Create an invoice. Subtotal, tax and total are computed server-side ($1–$1,000,000, max 60 line items)
fetch_invoices	List invoices with pagination and filters by status and date range
get_invoice	Get full invoice detail: line items, payment info, public link, QR code, stats and event timeline
update_invoice	Update an invoice. State machine draft → pending → paid; paid and cancelled are immutable
delete_invoice	Permanently delete an invoice. Cannot be undone — use status cancelled to keep it as history

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.

Tool	Description
create_survey	Create a survey attached to a sweepstakes, optionally with its full question set
fetch_surveys	List surveys with pagination, filtered by sweepstakes, enabled state or archived state
get_survey	Get full survey detail including its complete question set, sorted by page then order
update_survey	Update a survey. The question set is a full replacement and locks once responses exist
delete_survey	Permanently delete a survey, its questions, responses, stats and files. Cannot be undone
fetch_survey_responses	Get individual responses with each answer. Device/IP metadata is PII and off by default
fetch_survey_report	Get the aggregated report: totals, completion rate, device breakdown, timeline, distributions

Codes & Coupons Tools (14)

Writes require the Codes & Coupons module enabled on the account — they return 403 "module not enabled" otherwise. The four reads (fetch_code_stats, fetch_codes, get_code, get_code_settings) do not document that 403; if one of them answers 403, the cause is something else.

Tool	Description
fetch_code_stats	Count the codes of a sweepstakes by status
fetch_codes	List codes with the participant each one is assigned to. Server-side filters, search and sorting
get_code	Get one code by token, or by the code itself plus the sweepstakes token (point of sale)
create_codes	Import 1–1,000 codes you already have. Reports Created, Duplicates and Invalid separately
generate_codes	Generate up to 5,000 random codes with optional prefix, suffix, value and expiration
update_code	Partially update one code. null clears a field; the code itself can only be renamed while unassigned
delete_codes	Permanently delete up to 1,000 codes. Assigned, redeemed and voided codes are skipped. Requires confirm: true
assign_code	Assign an available code to a participant of the same sweepstakes. Does not notify anyone
unassign_code	Take a code back from a participant, clearing its redemption too. Requires confirm: true
redeem_code	Redeem a code by token, or by the code itself at the point of sale. Reversible
unredeem_code	Undo a redemption while keeping the assignment
get_code_settings	Get how the entry and AMOE pages hand out codes
update_code_settings	Configure code registration modes, generation and delivery for entry and AMOE pages
send_code	Send a code to the participant holding it by email and/or SMS. Cannot be recalled. Requires confirm: true

Messaging Tools (12)

Writes require the Send Message module enabled on the account — they return 403 "module not enabled" otherwise. The six reads do not document that 403.

Direct sending (send_message, send_code) is a separate switch from the module: an account with the module enabled can still get 403 until Sweeppea support enables direct messages. fetch_messaging_usage reports both, plus plan channels, allowance, sending pauses and 10DLC readiness.

Campaigns cannot be created through the API — they are created in the Sweeppea app. These tools read, pause, resume and cancel them.

Tool	Description
fetch_messaging_usage	Get messaging access, plan channels, allowance, sending pauses and 10DLC status
fetch_campaigns	List campaigns with filters by sweepstakes, channel, category, status and name
get_campaign	Get campaign content, audience, sender profile, counters and the actions its status allows
fetch_campaign_report	Get the campaign report. Rates are computed over messages sent, not over the audience
fetch_campaign_recipients	List recipients with delivery status, filtered by status or one exact address
pause_campaign	Pause a queued or sending campaign. Messages already handed to the carrier still go out
resume_campaign	Resume a paused campaign after re-checking everything that would stop it again
cancel_campaign	Cancel a campaign permanently. Cannot be resumed. Requires confirm: true
fetch_suppressions	List suppressed addresses: unsubscribes, STOP replies, complaints, bounces and manual entries
add_suppressions	Suppress up to 500 email addresses or phone numbers. Never downgrades an existing opt-out
remove_suppression	Remove a manually added suppression. Opt-outs, STOP replies and complaints are never removable. Requires confirm: true
send_message	Send a plain-text message by email and/or SMS to a participant of your account. Cannot be recalled. Requires confirm: true

Documentation Tools (1)

Tool	Description
fetch_documentation	Get help and support documentation articles with pagination and search

Utilities Tools (5)

Tool	Description
fetch_timezones	Get all available timezones with IANA identifiers and UTC offsets
fetch_states	Get all US states including DC, Puerto Rico, and territories
fetch_zipcodes	Search US zip codes by code, city, or state. Up to 10 results
fetch_areacodes	Search US telephone area codes by code or state. Up to 10 results
fetch_countries	Search countries by name, dial code, or ISO abbreviation. Up to 10 results

Testing Tools (1)

Tool	Description
hello_world	Simple test tool to verify MCP connection is working properly

---

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

Property	Value
Version	2025-11-25
Transport	Streamable HTTP
Authentication	Bearer token
Format	JSON-RPC 2.0
Endpoint	https://mcp.sweeppea.com/

---

License

MIT License - see LICENSE file for details.

(c) Sweeppea | All rights reserved