What Is the Secret Santa Raffle MCP?

The Secret Santa Raffle MCP (Model Context Protocol) server lets any AI assistant — ChatGPT, Claude, Gemini, take your pick — spin up a Monito Monita gift exchange draw programmatically, straight from natural language. Instead of filling in a web form, the user simply tells the AI who is joining, and the AI talks to our server to generate the draw automatically.

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

The Endpoint and Protocol

Requests travel over JSON-RPC 2.0 over HTTPS. The protocol version in use is 2025-06-18.

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

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

Content-Type: application/json

Running on MCP Protocol version 2025-06-18

This server exposes two channels on the same domain: POST /mcp, the default channel with the full toolset, meant for assistants like Claude; and POST /openai/mcp, the OpenAI-compliant channel used by the ChatGPT app, which only exposes the three public tools documented below. Both speak the same JSON-RPC 2.0 protocol under the hood.

The Handshake Step (Initialize)

Every MCP client has to complete an initialize handshake before calling any tools. Once it gets the response back, the client must then send a notifications/initialized message (no id field included).

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

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

create_draw, the JSON Schema

The main tool here is create_draw. It sets up a gift exchange draw with N participants (minimum 3), pairs them up randomly while respecting any exclusion rules, and hands back a drawId and shareCode for whatever comes next.

{
  "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

Parameter Data Type Required? What It Means
date string (date) Yes po Draw date in YYYY-MM-DD format. Has to be today or later.
participants array (min 3) Yes po The list of participants. Each one needs a name, email, and optional exclusions.
drawName string No Optional name for the draw. Falls back to "Secret Santa 2026" if left blank.
price string No The gift budget, written as free text (e.g. "£25", "$30").
message string No Custom invitation email body. Uses a localised default if you skip it.
locale string (BCP 47) No Determines the brand (SS/AS/MX/AI) and its localised templates. Falls back to the Accept-Language header.

The Tools on Offer

create_draw — Set Up a Draw

Sets up a gift exchange draw with N participants (minimum 3). Pairs everyone up randomly while honouring any exclusion rules. Returns drawId and shareCode for whatever you call next.

send_invitations_email — Email Out the Invitations

Sends a personalised email to every participant with a private link to join the draw. Can only be called once per draw.

Needs the drawId and shareCode returned by create_draw.

get_group_share_message — Generate a WhatsApp/Telegram Message

Puts together a ready-to-paste message for sharing in a group chat. No side effects here — nothing gets created and no emails are sent.

A Typical Integration Flow

1 Initialize — send the initialize handshake and get the server capabilities back.
2 notifications/initialized — finish the handshake (the server replies with 202 Accepted).
3 tools/list — see the three tools on offer.
4 tools/call create_draw — create the draw and grab drawId + shareCode from structuredContent.
5 Option A: tools/call send_invitations_email — send the emails out to every participant.
6 Option B: tools/call get_group_share_message — get a message ready to paste into WhatsApp or Telegram.

How Language & Brand Routing Works

The locale parameter you pass in each tool call decides which brand and templates get used. Always include a locale for the best results.

locale Which Brand Game Name Used
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 the AI Integration

Nothing Sticks Around

Names and email addresses shared through the chat are used only to generate the draw. They are never stored inside the language model or reused to train it further.

Encrypted All the Way

Every exchange between the AI assistant and our servers travels over secure HTTPS.

Where Your Data Lives

Once the raffle is created, all personal data (emails and assignments) moves to our own secure infrastructure, fully in line with GDPR.

You're Always in Control

The AI only ever sees the data the organiser explicitly shares during the conversation, nothing more.

When Things Go Wrong

The server returns tool-level errors with isError: true in the result, so it is clear when a "tool failed" versus a "tool does not exist".

Error Code What Happened
lottery_impossible The exclusions make a valid draw impossible. Try removing an exclusion or two, or add more participants.
validation The backend rejected the data (422 with errors). Check the response for exactly which fields failed.
not_found That drawId does not exist. Double-check it or recreate the draw.
forbidden Wrong shareCode. Should not happen if it came straight from the matching create_draw response.
already_sent Invitations already went out for this draw. Bulk email can only be triggered once per draw.
server A temporary backend hiccup (5xx). Worth retrying again in a few minutes.

How Does This Work for Regular Users?

Prefer a plain-English, step-by-step guide instead of the technical stuff? Check out our blog post on how anyone can set up a Monito Monita just by chatting with ChatGPT.

Check Out the Plain-English Guide

While you're at it, check these out

Ready to Create Your Own Draw?

Skip the AI altogether and set up your Monito Monita directly on our website. Free, fast, and no registration needed.

Start My Free Draw