sweeppea-mcp ~ docs

Sweeppea MCP Server — AI-Powered Sweepstakes Management

$ MCP Server v1.15.0

Model Context Protocol for Sweepstakes Management

Available for Sweeppea clients in the United States and Canada

# How It Works

The Sweeppea MCP (Model Context Protocol) 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.


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

No local setup required — just point your MCP (Model Context Protocol) client to the endpoint and authenticate.

# Authentication & Pricing

This MCP (Model Context Protocol) server requires a Sweeppea API Key tied to an active subscription.

Here's the reason: running sweepstakes in the United States and/or Canada is legally complex. Each of the states 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 (Model Context Protocol) client using the configuration guides below

Documentation:

# Quick Start

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

Using Claude Code CLI. See Platform Setup for Claude Desktop/Cowork and other clients.

# Available Tools (66)

health_check

Verify connection to Sweeppea API and validate your API key.

no params
get_profile

Get user profile information for a Sweeppea account.

no params
get_business

Get business information including company details and address.

no params
get_plan

Get subscription plan details including pricing, limits and features.

no params
Entry Page
get_entry_fields

Get all form fields for a sweepstakes entry page. Use before adding participants.

sweepstakes_token
Entry Page
get_entry_settings

Get all entry page settings: display, colors, compliance, confirmation, winners, age gate, AMOE, and more.

sweepstakes_token
Entry Page
update_entry_settings

Update 1-5 entry page settings per request. Supports 80+ configurable fields.

sweepstakes_token settings
Sweepstakes
fetch_sweepstakes

Get all sweepstakes associated with your account.

no params
Sweepstakes
create_sweepstakes

Create a new sweepstakes with type, handler, dates, and times.

sweepstakes_name sweepstakes_type handler start_date end_date start_time end_time create_in_calendar sync_with_winners
Sweepstakes
update_sweepstakes

Update an existing sweepstakes (name, dates, times).

sweepstakes_token sweepstakes_name start_date end_date start_time end_time
Sweepstakes
clone_sweepstakes

Clone an existing sweepstakes with new parameters and dates.

handler handler_new sweepstakes_name start_date end_date start_time end_time
Sweepstakes
pause_sweepstakes

Pause a sweepstakes, setting it to inactive while preserving data.

sweepstakes_token
Sweepstakes
unpause_sweepstakes

Reactivate a paused sweepstakes to allow new entries.

sweepstakes_token
Sweepstakes
delete_sweepstakes

Permanently delete a sweepstakes and all associated data.

sweepstakes_token
Participants
add_participant

Add a new participant to a sweepstakes with custom fields.

sweepstakes_token email fields phone bonus_entries
Participants
get_participant

Fetch a single participant by token, email, or phone number.

sweepstakes_token participant_token email phone
Participants
fetch_participants

List participants with pagination (20/page), search, and date filters.

sweepstakes_token search opt_in_date start_date end_date page
Participants
count_participants

Get participant counts with optional filtering by type and date.

sweepstakes_token filter_type start_date end_date
Participants
update_bonus_entries

Overwrite the bonus entries value for a participant.

sweepstakes_token participant_token bonus_entries
Participants
delete_participant

Permanently remove a participant from a sweepstakes.

sweepstakes_token participant_token
Groups
fetch_groups

Get all groups from a sweepstakes for participant segmentation.

sweepstakes_token
Groups
create_group

Create a new group within a sweepstakes.

sweepstakes_token group_name
Groups
update_group

Update the name of an existing group in a sweepstakes.

sweepstakes_token group_token group_name
Groups
delete_group

Delete a group. Cannot delete primary, locked, or groups with participants.

sweepstakes_token group_token
Notes
fetch_notes

Get all notes, decrypted and in reverse chronological order.

no params
Notes
get_note

Fetch a single note by token. Content is automatically decrypted.

note_token
Notes
create_note

Create a new note. Content is encrypted using AES-256-CBC.

title content pinned
Notes
update_note

Update an existing note. Supports partial updates.

note_token title content pinned
Notes
delete_note

Permanently delete a note. This action cannot be undone.

note_token
Calendar
fetch_calendar_events

Get all calendar events with dates, times, and status.

no params
Calendar
get_calendar_event

Get a single calendar event by its token with full details.

event_token
Calendar
create_calendar_event

Create a new calendar event with title, dates, and notifications.

title start_date end_date description location start_time end_time
Calendar
update_calendar_event

Update an existing calendar event. Cannot update to past dates.

event_token title start_date end_date
Calendar
delete_calendar_event

Permanently delete a calendar event. Cannot be undone.

event_token
Rules
fetch_rules

Get all official rules including primary and secondary rules.

sweepstakes_token
Rules
create_rule

Create a new official rules document with HTML content.

sweepstakes_token title document_content
Rules
update_rule

Update an existing official rules document. Supports partial updates.

sweepstakes_token rules_token title document_content
Rules
delete_rule

Permanently delete an official rules document. Cannot be undone.

sweepstakes_token rules_token
Rules
create_rules_wizard

Generate official rules via 14-step wizard. Complete HTML rules server-side.

sweepstakes_token arv sweepstakes_name prize_description sponsor_name method_of_entry +19 more required +15 conditional
Billing
fetch_wallet_transactions

Get all wallet transactions including credits, debits, and payments.

no params
Billing
fetch_billing_transactions

Get all billing transactions including invoices and amounts.

no params
Billing
fetch_billing_consumptions

Get monthly and yearly billing consumption totals.

no params
Billing
fetch_data_transfer

Get data transfer records for a specific sweepstakes with costs.

sweepstakes_token
Support
fetch_open_tickets

Get open tickets with pagination, search, platform and priority filters.

search platform priority page
Support
fetch_closed_tickets

Get closed tickets with pagination, search, platform and priority filters.

search platform priority page
Support
get_ticket

Get full ticket details by case number including notes and files.

case_number
Support
create_ticket

Create a new support ticket with title, description, priority, and optional admin assignment.

title description priority
Support
resolve_ticket

Close/resolve an open support ticket.

case_id
Support
update_ticket

Update an open support ticket. At least one field required.

case_id title description
Support
delete_ticket

Permanently delete an open support ticket. Cannot be undone.

case_id
Winners
draw_winners

Execute an immediate random winner drawing from a sweepstakes.

sweepstakes_token how_many_winners group completed_entries include_opted_out exclude_spam
Winners
fetch_winners

Get winners from a sweepstakes with pagination and search.

sweepstakes_token page items_per_page search
Winners
schedule_drawing

Schedule a future winner drawing with timezone and notification options.

sweepstakes_token group how_many_winners end_date end_time timezone selected_action schedule_mode
Winners
fetch_scheduled_drawings

Get all scheduled drawings for a sweepstakes.

sweepstakes_token
Winners
delete_scheduled_drawing

Cancel a pending scheduled drawing.

sweepstakes_token schedule_token
Documentation
fetch_documentation

Get help and support documentation articles with pagination and search.

page limit search
To-Do
create_todo

Create an internal To-Do item with priority and deadline (admin only).

title priority description deadline resource_affected pin
To-Do
fetch_todos

Get To-Do items with pagination, search, and filters (admin only).

search status priority resource pinned page
To-Do
update_todo

Update an existing To-Do item with partial updates (admin only).

todo_token title priority status completion deadline
To-Do
delete_todo

Permanently delete a To-Do item (admin only).

todo_token
Utilities
fetch_timezones

Get all available timezones with IANA identifiers and UTC offsets.

no params
Utilities
fetch_states

Get all US states including DC, Puerto Rico, and territories.

no params
Utilities
fetch_zipcodes

Search US zip codes by code, city, or state. Up to 10 results.

search
Utilities
fetch_areacodes

Search US telephone area codes by code or state. Up to 10 results.

search
Utilities
fetch_countries

Search countries by name, dial code, or ISO abbreviation. Up to 10 results.

search
Files
upload_file

Upload a file to the user's Drive (base64, max 10MB). Supports PDF, DOC, images, and more.

filenamemime_typefile_dataprivate
Files
fetch_files

List all files with storage usage, categories, and pagination.

pagelimit
Files
delete_file

Permanently delete a file from the user's Drive and S3 storage.

file_token
Files
send_file

Send a file as an email attachment (max 5MB) using the Sweeppea template.

file_tokenrecipient_emailemail_subjectemail_message
Testing
hello_world

Simple test tool to verify MCP connection is working properly.

name

# Usage Examples

initialize 
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_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)

Add server with a single command

terminal 
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

Add to claude_desktop_config.json (requires Node.js installed)

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
claude_desktop_config.json 
{
  "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)

Step-by-step:

  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
mcp.json 
{
  "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)

Step-by-step:

  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
mcp_config.json 
{
  "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

mcp.json 
{
  "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)

settings.json 
{
  "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

Step-by-step:

  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

Note: On first connection, Agent Zero will automatically install the required libraries to connect to the MCP server.

MCP Server Config 
{
  "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"
      }
    }
  }
}
Troubleshooting: Common connection issues

Error: SSEError: Expected Content-Type 'text/event-stream', got 'application/json'

This happens when "type" is set to "sse" instead of "streamable-http". Sweeppea uses MCP Protocol 2025-11-25 with Streamable HTTP transport, not SSE.

Error: UI "Apply" button is disabled (greyed out)

Known bug in Agent Zero v0.9.7-10. The UI rejects valid JSON configurations. Workaround: edit the config file directly and restart.

Manual fix (when UI is broken) 
# 1. Backup
cp /a0/tmp/settings.json /a0/tmp/settings_backup.json

# 2. Edit with Python (mcp_servers is a JSON string inside JSON)
python3 -c "
import json
with open('/a0/tmp/settings.json', 'r') as f:
    config = json.load(f)
mcp = json.loads(config['mcp_servers'])
mcp['mcpServers']['sweeppea']['type'] = 'streamable-http'
mcp['mcpServers']['sweeppea']['headers']['MCP-Protocol-Version'] = '2025-11-25'
config['mcp_servers'] = json.dumps(mcp)
with open('/a0/tmp/settings.json', 'w') as f:
    json.dump(config, f, indent=2)
print('Done')
"

# 3. Restart Agent Zero
docker restart agent-zero

Important: In settings.json, the field mcp_servers is a JSON string (not an object). You must parse it, modify it, stringify it back, then save.

> Antigravity by Google

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

mcp_config.json 
{
  "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

version 2025-11-25
transport streamable-http
auth bearer token
format json-rpc 2.0