What is the Secret Santa Raffle MCP?

The Secret Santa Raffle MCP (Model Context Protocol) server enables any AI assistant — such as ChatGPT, Claude, or Gemini — to create gift exchange draws programmatically using natural language. Instead of filling out web forms, users simply tell the AI who is participating, and the AI communicates with our server to generate the draw automatically.

The server implements JSON-RPC 2.0 over HTTPS, following the MCP specification (version 2025-06-18). It exposes three tools: create_draw, send_invitations_email, and get_group_share_message.

Endpoint & Protocol

All requests are sent to a single endpoint using JSON-RPC 2.0 over HTTPS. The protocol version is 2025-06-18.

POST https://mcp.secretsantaraffle.net/mcp

Content-Type: application/json

MCP Protocol version: 2025-06-18

Handshake (Initialize)

Every MCP client must complete an initialize handshake before invoking tools. After receiving the response, the client must send a notifications/initialized message (no id field).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

After the initialize response, send: { "jsonrpc": "2.0", "method": "notifications/initialized" } — the server replies 202 Accepted with an empty body.

create_draw — JSON Schema

The main tool is create_draw. It creates a gift exchange draw with N participants (minimum 3), matches them randomly respecting exclusion constraints, and returns a drawId and shareCode for subsequent operations.

{
  "type": "object",
  "required": ["date", "participants"],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Draw date, YYYY-MM-DD. Today or future."
    },
    "participants": {
      "type": "array",
      "minItems": 3,
      "description": "Minimum 3 participants. The first is treated as the organiser.",
      "items": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 255 },
          "email": { "type": "string", "format": "email" },
          "exclusions": {
            "type": "array",
            "items": { "type": "string", "format": "email" },
            "description": "Emails of participants this person must NOT be matched with."
          }
        }
      }
    },
    "drawName": {
      "type": "string",
      "maxLength": 255,
      "description": "Optional. Defaults to e.g. \"Secret Santa 2026\"."
    },
    "price": {
      "type": "string",
      "description": "Gift budget, free text. Examples: \"£25\", \"$30\"."
    },
    "message": {
      "type": "string",
      "description": "Invitation email body. If omitted, a localised default is used. Placeholder \"ParticipantX\" replaced with the recipient's name."
    },
    "locale": {
      "type": "string",
      "description": "BCP 47 language tag. E.g. \"en-GB\", \"es-ES\", \"es-MX\". Determines brand and templates."
    }
  }
}

Field reference

Field Type Required Description
date string (date) Yes Draw date in YYYY-MM-DD format. Must be today or future.
participants array (min 3) Yes List of participants. Each has name, email, and optional exclusions.
drawName string No Optional name for the draw. Defaults to "Secret Santa 2026".
price string No Gift budget as free text (e.g. "£25", "$30").
message string No Custom invitation email body. Uses localised default if omitted.
locale string (BCP 47) No Determines brand (SS/AS/MX/AI) and localised templates. Falls back to Accept-Language header.

Available Tools

create_draw — Create a Draw

Creates a gift exchange draw with N participants (minimum 3). Matches participants randomly respecting exclusion constraints. Returns drawId and shareCode for subsequent operations.

send_invitations_email — Send Invitations by Email

Sends a personalised email to each participant with a link to reveal their assignment in the mobile app. Can only be invoked once per draw.

Requires drawId and shareCode from create_draw.

get_group_share_message — Generate WhatsApp/Telegram Message

Generates a ready-to-paste message for sharing in a group chat. No side effects — no data is created or emails sent.

Typical Integration Flow

1 Initialize → Send the initialize handshake and receive server capabilities.
2 notifications/initialized → Complete the handshake (server replies 202 Accepted).
3 tools/list → Discover the three available tools.
4 tools/call create_draw → Create the draw and receive drawId + shareCode from structuredContent.
5 Option A: tools/call send_invitations_email → Send emails to all participants.
6 Option B: tools/call get_group_share_message → Get a WhatsApp/Telegram-ready message.

Language & Brand Routing

The locale parameter in each tool's arguments determines which brand and templates are used. Always include locale for best results.

locale Brand Game
es-ES, es-AR, es-UY AI (Amigo Invisible) Amigo Invisible
es-MX MX (Intercambio de Regalos) Intercambio de Regalos
es-CO, es-CL, es-PE, es-VE, es AS (Amigo Secreto) Amigo Secreto
en-* (or omitted) SS (Secret Santa) Secret Santa Raffle

Security & Privacy in AI Integration

Ephemeral Processing

Names and email addresses provided via the chat interface are used solely for generating the draw. They are not stored within the language model nor used for future AI training.

End-to-End Encryption

All communication between the AI assistant and our servers is conducted over secure HTTPS protocols.

Data Custody

Once the raffle is created, the management of personal data (emails and assignments) is transferred to our secure infrastructure, in full compliance with GDPR regulations.

User Control

The AI only accesses the data explicitly provided by the organiser during the natural language conversation.

Error Handling

The server returns tool-level errors with isError: true in the result, distinguishing "tool failed" from "tool doesn't exist".

Error Cause
lottery_impossible The exclusions prevent a valid draw. Suggest removing some exclusions or adding more participants.
validation The backend rejected the data (422 with errors). Lists the fields that failed.
not_found The drawId does not exist. Suggest verifying or recreating the draw.
forbidden Incorrect shareCode. Should not occur if it came from the same create_draw response.
already_sent Invitations were already sent for this draw. Individual resends are a premium feature.
server Temporary backend error (5xx). Suggest retrying in a few minutes.

How Does It Work for Users?

If you prefer a step-by-step guide without technical jargon, check out our blog post explaining how anyone can create a Secret Santa draw simply by talking to ChatGPT.

Read the User Guide

You might also like

Ready to Create Your Draw?

Skip the AI and create your Secret Santa draw directly on our website. Free, fast, no registration needed.

Create Free Draw