Sweeppea MCP is a Streamable HTTP MCP server (JSON-RPC 2.0, Bearer-token auth) that bridges AI assistants to the Sweeppea API v3 for legally compliant sweepstakes management in the US and Canada — though the supplied schema exposes only sweeppea_connect, which returns connection details and claims 66 tools (the README advertises 109).
Account – health check, profile, business info, subscription plan
Sweepstakes lifecycle – list (with computed state), create, update, clone, pause/unpause, delete
Entry pages – read entry fields/settings, update 80+ settings (1–5 per call)
Participants – add, get, list/search, count, update bonus entries, delete
Groups – create, list, rename, delete for segmentation
Notes – create (AES-256-CBC encrypted), read/decrypt, update, delete
Calendar – list, get, create, update, delete events with notifications
Official rules – list, create, update, delete, plus a 14-step rules wizard generating full HTML
Winners & draws – list winners, draw randomly, schedule/fetch/delete drawings
Billing & wallet – wallet transactions, billing transactions, consumption totals, data transfer costs
Support tickets – open/closed lists, get, create, resolve, update, delete
To-Dos – list, create, update, delete internal items
Files (Drive) – list with storage usage, upload (base64), presigned URL, send as email attachment, delete
Invoices (module, off by default) – create/fetch/get/update/delete with server-side totals and draft→pending→paid state machine
Surveys (module, off by default) – create/update surveys and question sets, list responses, aggregated reports
Codes & Coupons – stats, list, get, import/generate up to 1,000/5,000 codes, update, assign/unassign, redeem/unredeem, settings, send
Messaging – usage/10DLC status, campaigns (list, get, pause, resume, cancel, reports, recipients), suppressions, direct send
Documentation – searchable help/support articles
Utilities – timezones, US states, zip codes, area codes, countries
Testing – hello_world connection check
Guardrails – inviolable legal checks (AMOE, COPPA/13+, alcohol & nicotine 21+ gates, no nicotine prizes) and dynamic rules on create/update calls; irreversible actions (delete_*, send_message, send_code, cancel_campaign, remove_suppression, unassign_code) require confirm: true
___
/ __|_ __ _____ ___ _ __ _ __ ___ __ _
\__ \ V V / -_) -_) '_ \ '_ \/ -_) _` |
|___/\_/\_/\___\___| .__/ .__/\___\__,_|
|_| |_|Model Context Protocol for Sweepstakes Management
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 v3No local setup required — just point your MCP client to the endpoint and authenticate.
Related MCP server: Marketing Brain
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:
Create an account at www.sweeppea.com
Choose a plan that fits your needs
Get your API Key from the API dashboard
Connect your MCP client using the configuration guides below
Documentation:
MCP Server docs: mcpdocs.sweeppea.com
API documentation: apidocs.sweeppea.com
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.
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.
Tool | Description |
| Verify connection to Sweeppea API and validate your API key |
| Get user profile information for a Sweeppea account |
| Get business information including company details and address |
| Get subscription plan details including pricing, limits and features |
Tool | Description |
| Get all form fields for a sweepstakes entry page. Use before adding participants |
| Get all entry page settings: display, colors, compliance, confirmation, winners, age gate, AMOE, and more |
| Update 1-5 entry page settings per request. Supports 80+ configurable fields |
Tool | Description |
| List sweepstakes with pagination. Returns a summary with a computed lifecycle state (scheduled, running, ended) |
| Create a new sweepstakes with type, handler, dates, and times |
| Update an existing sweepstakes (name, dates, times) |
| Clone an existing sweepstakes with new parameters and dates |
| Pause a sweepstakes, setting it to inactive while preserving data |
| Reactivate a paused sweepstakes to allow new entries |
| Permanently delete a sweepstakes and all associated data |
Tool | Description |
| Add a new participant to a sweepstakes with custom fields. Both email and phone are required |
| Fetch a single participant by token, email, or phone number |
| List participants with pagination (20/page), search, and date filters |
| Get participant counts with optional filtering by type and date |
| Update the bonus entries value for a participant in a sweepstakes |
| Permanently remove a participant from a sweepstakes |
Tool | Description |
| Get all groups from a sweepstakes for participant segmentation |
| Create a new group within a sweepstakes |
| Update the name of an existing group in a sweepstakes |
| Delete a group. Cannot delete primary, locked, or groups with participants |
Tool | Description |
| Get all notes, decrypted and in reverse chronological order |
| Fetch a single note by token. Content is automatically decrypted |
| Create a new note. Content is encrypted using AES-256-CBC |
| Update an existing note. Supports partial updates |
| Permanently delete a note. This action cannot be undone |
Tool | Description |
| Get all calendar events with dates, times, and status |
| Get a single calendar event by its token with full details |
| Create a new calendar event with title, dates, and notifications |
| Update an existing calendar event. Cannot update to past dates |
| Permanently delete a calendar event. Cannot be undone |
Tool | Description |
| Get all official rules including primary and secondary rules |
| Create a new official rules document with HTML content |
| Update an existing official rules document. Supports partial updates |
| Permanently delete an official rules document. Cannot be undone |
| Generate official rules via 14-step wizard. Complete HTML rules server-side |
Tool | Description |
| Get all wallet transactions including credits, debits, and payments |
| Get all billing transactions including invoices and amounts |
| Get monthly and yearly billing consumption totals |
| Get data transfer records for a specific sweepstakes with costs |
Tool | Description |
| Get open tickets with pagination, search, platform and priority filters |
| Get closed tickets with pagination, search, platform and priority filters |
| Get full ticket details by case number including notes and files |
| Create a new support ticket with title, description, priority, assignee and platform |
| Close/resolve an open support ticket |
| Update an open support ticket. At least one field required |
| Permanently delete an open support ticket. Cannot be undone |
Tool | Description |
| Get winners from a sweepstakes with pagination and search |
| Draw random winners from eligible participants |
| Schedule a future winner drawing for a sweepstakes |
| Get all scheduled drawings for a sweepstakes |
| Delete a pending scheduled drawing. Only pending drawings can be deleted |
Tool | Description |
| Get all To-Do items with pagination (20 per page), search, and advanced filters |
| Create a new internal To-Do item |
| Update an existing To-Do item. Supports partial updates |
| Permanently delete a To-Do item. This action cannot be undone |
Tool | Description |
| List all files in the user's Drive with storage usage, categories, and pagination |
| Upload a file to the user's Drive. The file must be base64-encoded |
| Generate a short-lived presigned S3 URL to download or preview a file from the user's Drive |
| Send a file from the user's Drive as an email attachment |
| Permanently delete a file from the user's Drive |
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 an invoice. Subtotal, tax and total are computed server-side ($1–$1,000,000, max 60 line items) |
| List invoices with pagination and filters by status and date range |
| Get full invoice detail: line items, payment info, public link, QR code, stats and event timeline |
| Update an invoice. State machine draft → pending → paid; paid and cancelled are immutable |
| Permanently delete an invoice. Cannot be undone — use status |
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 a survey attached to a sweepstakes, optionally with its full question set |
| List surveys with pagination, filtered by sweepstakes, enabled state or archived state |
| Get full survey detail including its complete question set, sorted by page then order |
| Update a survey. The question set is a full replacement and locks once responses exist |
| Permanently delete a survey, its questions, responses, stats and files. Cannot be undone |
| Get individual responses with each answer. Device/IP metadata is PII and off by default |
| Get the aggregated report: totals, completion rate, device breakdown, timeline, distributions |
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 |
| Count the codes of a sweepstakes by status |
| List codes with the participant each one is assigned to. Server-side filters, search and sorting |
| Get one code by token, or by the code itself plus the sweepstakes token (point of sale) |
| Import 1–1,000 codes you already have. Reports Created, Duplicates and Invalid separately |
| Generate up to 5,000 random codes with optional prefix, suffix, value and expiration |
| Partially update one code. |
| Permanently delete up to 1,000 codes. Assigned, redeemed and voided codes are skipped. Requires |
| Assign an available code to a participant of the same sweepstakes. Does not notify anyone |
| Take a code back from a participant, clearing its redemption too. Requires |
| Redeem a code by token, or by the code itself at the point of sale. Reversible |
| Undo a redemption while keeping the assignment |
| Get how the entry and AMOE pages hand out codes |
| Configure code registration modes, generation and delivery for entry and AMOE pages |
| Send a code to the participant holding it by email and/or SMS. Cannot be recalled. Requires |
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_usagereports 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 |
| Get messaging access, plan channels, allowance, sending pauses and 10DLC status |
| List campaigns with filters by sweepstakes, channel, category, status and name |
| Get campaign content, audience, sender profile, counters and the actions its status allows |
| Get the campaign report. Rates are computed over messages sent, not over the audience |
| List recipients with delivery status, filtered by status or one exact address |
| Pause a queued or sending campaign. Messages already handed to the carrier still go out |
| Resume a paused campaign after re-checking everything that would stop it again |
| Cancel a campaign permanently. Cannot be resumed. Requires |
| List suppressed addresses: unsubscribes, STOP replies, complaints, bounces and manual entries |
| Suppress up to 500 email addresses or phone numbers. Never downgrades an existing opt-out |
| Remove a manually added suppression. Opt-outs, STOP replies and complaints are never removable. Requires |
| Send a plain-text message by email and/or SMS to a participant of your account. Cannot be recalled. Requires |
Tool | Description |
| Get help and support documentation articles with pagination and search |
Tool | Description |
| Get all available timezones with IANA identifiers and UTC offsets |
| Get all US states including DC, Puerto Rico, and territories |
| Search US zip codes by code, city, or state. Up to 10 results |
| Search US telephone area codes by code or state. Up to 10 results |
| Search countries by name, dial code, or ISO abbreviation. Up to 10 results |
Tool | Description |
| Simple test tool to verify MCP connection is working properly |
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"}
}
}
}'claude mcp add sweeppea https://mcp.sweeppea.com/ \
--transport http \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "MCP-Protocol-Version: 2025-11-25"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/mcp.json (global) or .cursor/mcp.json (project)
Create or edit the config file with the JSON below
Replace YOUR_API_KEY with your Sweeppea API Key
Restart Cursor
Go to Settings > Tools & MCP
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"
}
}
}
}~/.codeium/windsurf/mcp_config.json (global)
Create or edit the config file with the JSON below
Replace YOUR_API_KEY with your Sweeppea API Key
Go to Settings > Cascade > MCP Servers
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"
}
}
}
}.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/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"
}
}
}
}Open-source AI agent framework with MCP support.
Go to Settings > MCP/A2A > MCP Servers
Add the JSON configuration below
Replace YOUR_API_KEY with your Sweeppea API Key
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"
}
}
}
}~/.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"
]
}
}
}Property | Value |
Version |
|
Transport | Streamable HTTP |
Authentication | Bearer token |
Format | JSON-RPC 2.0 |
Endpoint |
|
MIT License - see LICENSE file for details.
(c) Sweeppea | All rights reserved
Returns connection details and configuration instructions for the Sweeppea MCP Server. This remote server provides 109 tools across 20 categories for managing legally compliant sweepstakes promotions in the United States and Canada. Use this tool to obtain the endpoint URL, required authentication headers, and platform-specific setup guides for Claude Desktop, Cursor, Windsurf, and other MCP clients. Requires an active Sweeppea subscription and API key from sweeppea.com.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | Target MCP client platform for configuration instructions. Supported: claude-desktop, claude-code, cursor, windsurf, generic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It usefully discloses the authentication requirement and subscription prerequisite, which is the key behavioral fact for this tool. However, it never explicitly states that the call is read-only/non-mutating, whether it stores anything, or how failures (invalid API key) surface.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the purpose, which is good. However, the middle sentence about '109 tools across 20 categories' and 'legally compliant sweepstakes promotions in the United States and Canada' is marketing framing that does not help an agent invoke this one-parameter tool, adding bulk without function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must convey return content, and it does: endpoint URL, required authentication headers, and platform-specific setup guides. Prerequisites are also covered. It is nearly complete for a low-complexity, single-optional-parameter discovery tool; only explicit read-only/error semantics are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'platform' parameter is fully documented with an enum in the schema. The description reinforces this by listing supported clients (Claude Desktop, Cursor, Windsurf, other MCP clients), but adds no format or default behavior beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Returns connection details and configuration instructions for the Sweeppea MCP Server.' It goes further by naming the concrete artifacts returned (endpoint URL, auth headers, setup guides) and the server's scope (109 tools / 20 categories), so an agent knows exactly what this tool is for. There are no sibling tools to distinguish it from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this tool to obtain the endpoint URL, required authentication headers, and platform-specific setup guides' gives clear activation context, and the prerequisites (active Sweeppea subscription and API key) are stated. There are no alternative tools to exclude against, but it also does not state any when-not condition (e.g., that it only needs to be called once during setup).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.22.0sweeppea_connect1 field changedInput schema / properties / platformAdded value: +{
+ "description": "Target MCP client platform for configuration instructions. Supported: claude-desktop, claude-code, cursor, windsurf, generic.",
+ "enum": [
+ "claude-desktop",
+ "claude-code",
+ "cursor",
+ "windsurf",
+ "generic"
+ ],
+ "type": "string"
+}v0.1.0sweeppea_connectScored across 1 tool
With only a single tool, there is no possibility of overlap or misselection between tools. The lone tool has a clear, distinct purpose (returning connection details), though it is a meta/gateway tool rather than domain functionality.
The single tool follows a clear snake_case pattern with a vendor prefix (sweeppea_connect), which is readable and predictable. Consistency cannot be meaningfully assessed with one tool, but no naming issues are present.
Exposing only 1 tool for a server that advertises 109 tools across 20 categories is a severe mismatch. The lone tool provides no actual sweepstakes functionality, making the surface effectively empty.
The surface offers no CRUD or lifecycle operations for the stated sweepstakes domain; users must fetch connection details and then rely entirely on an external server. No create/read/update/delete or promotion management capabilities are exposed here.
Official MCP server for twitterapis.com. Read and write Twitter/X: search, users, tweets, DMs.
Official Porkbun MCP server: domains, DNS, SSL, hosting and Cloudflare via the Porkbun API.
Official MCP server for Certifier to issue, manage, and track certificates and badges.
Official MCP server for OmniDimension. Drive voice agents, dispatch calls, and run bulk campaigns.
