Developer Documentatie: MCP-Integratie

Wat is de Secret Santa Raffle MCP?

De Secret Santa Raffle MCP-server (Model Context Protocol) stelt elke AI-assistent — zoals ChatGPT, Claude of Gemini — in staat om programmatisch cadeau-uitwisselingstrekkingen te maken met natuurlijke taal. In plaats van webformulieren in te vullen, vertelt de gebruiker de AI gewoon wie er meedoen, en de AI communiceert met onze server om de trekking automatisch te genereren.

De server implementeert JSON-RPC 2.0 over HTTPS, volgens de MCP-specificatie (versie 2025-06-18). Hij biedt drie publieke tools: create_draw, send_invitations_email en get_group_share_message.

Endpoint & Protocol

Verzoeken worden verstuurd via JSON-RPC 2.0 over HTTPS. De protocolversie is 2025-06-18.

Deze server biedt twee kanalen op hetzelfde domein: POST /mcp — het standaardkanaal met de volledige toolset, voor assistenten zoals Claude; en POST /openai/mcp — het OpenAI-conforme kanaal dat de ChatGPT-app gebruikt, dat alleen de drie hieronder gedocumenteerde publieke tools biedt. Beide spreken hetzelfde JSON-RPC 2.0-protocol.

Handshake (Initialize)

Elke MCP-client moet een initialize-handshake afronden voordat tools worden aangeroepen. Na ontvangst van de reactie moet de client een notifications/initialized-bericht sturen (zonder id-veld).

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

Stuur na de initialize-reactie: { "jsonrpc": "2.0", "method": "notifications/initialized" } — de server antwoordt met 202 Accepted en een lege body.

create_draw — JSON Schema

De belangrijkste tool is create_draw. Deze maakt een cadeau-uitwisselingstrekking met N deelnemers (minimaal 3), koppelt ze willekeurig met inachtneming van uitsluitingsregels, en geeft een drawId en shareCode terug voor vervolgacties.

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

Veldoverzicht

Beschikbare Tools

Typische Integratiestroom

Taal- en Merkroutering

De parameter locale in de argumenten van elke tool bepaalt welk merk en welke sjablonen worden gebruikt. Geef altijd locale op voor het beste resultaat.

Foutafhandeling

De server geeft fouten op tool-niveau terug met isError: true in het resultaat, en onderscheidt zo "tool is mislukt" van "tool bestaat niet".