MCP-Server

Überblick

Das Model Context Protocol (MCP) ist ein offener Standard, mit dem KI-Assistenten externe Werkzeuge nutzen können. Unser MCP-Server bietet die Funktionen der REST-API als Tools an, die der Assistent selbst aufrufen kann.

In der Praxis sieht das so aus: Du sagst deinem Assistenten „Mach einen Adventskalender für unseren Newsletter, hinter jedem Türchen ein Rabatt, Türchen öffnen um 8“, beantwortest zwei, drei Fragen, und ein paar Minuten später hast du einen öffentlichen Link.

• Einen Kalender im Gespräch planen und mit den richtigen Terminen, der richtigen Zeitzone und dem passenden Design anlegen.
• Alle Türchen aus einer Liste, einer Tabelle oder einem eingefügten Produktfeed füllen.
• Einzelne Türchen später ändern („Tausch Türchen 12 gegen die neue Geschenkkarte“).
• Nach Zahlen fragen („Welche Türchen wurden am seltensten geöffnet?“).

Zugang

Der MCP-Server nutzt dieselben Schlüssel wie die API und ist in Premium (199 € pro Jahr) und Enterprise (1.299 € pro Jahr) ohne Aufpreis enthalten. Schlüssel vergeben wir von Hand; schreib an [email protected].

Der Assistent hat genau die Funktionen deines Tarifs. Er kann den Tarif nicht wechseln, nichts bezahlen und keine Abrechnungsdaten ändern. Wenn du etwas verlangst, das dein Tarif nicht enthält, sagt er dir, welchen Tarif du brauchst und wo du ihn wechselst.

Serveradresse

Der Server spricht MCP über Streamable HTTP unter https://mcp.adventskalendererstellen.de/mcp. Zur Authentifizierung dient der API-Schlüssel als Bearer-Token.

curl https://mcp.adventskalendererstellen.de/health
# {"status":"ok","protocol":["2025-06-18","2025-03-26"]}

Deinen Client einrichten

Claude Code

claude mcp add --transport http advent-calendar \
  https://mcp.adventskalendererstellen.de/mcp \
  --header "Authorization: Bearer $ACM_API_KEY"

Claude Desktop

Claude Desktop bindet Remote-Server über mcp-remote an. Trag Folgendes in claude_desktop_config.json ein und starte die App neu.

{
  "mcpServers": {
    "advent-calendar": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.adventskalendererstellen.de/mcp",
        "--header", "Authorization: Bearer ${ACM_API_KEY}"
      ],
      "env": { "ACM_API_KEY": "sk_live_..." }
    }
  }
}

Cursor und andere Clients

Clients, die Remote-Server direkt unterstützen, brauchen nur die URL und den Header.

{
  "mcpServers": {
    "advent-calendar": {
      "url": "https://mcp.adventskalendererstellen.de/mcp",
      "headers": { "Authorization": "Bearer ${env:ACM_API_KEY}" }
    }
  }
}

Nimm einen sk_test_-Schlüssel, solange du etwas ausprobierst. Testkalender sehen echt aus, tragen ein Test-Banner und verschwinden nach 30 Tagen.

Tools

Ein Tool zum Löschen eines Kalenders gibt es bewusst nicht. Löschen bleibt eine Entscheidung, die du im Editor oder über die API triffst.

Tool-Definitionen

Jedes Tool kommt mit einem JSON Schema für seine Eingabe und einer Beschreibung, die für das Modell geschrieben ist. Die Beschreibungen enthalten die Regeln, an die sich der Assistent halten muss, zum Beispiel dass er keine Gutscheincodes erfinden darf.

{
  "name": "fill_doors",
  "description": "Writes content into several doors of a calendar at once. Only use content the user gave or approved. Never invent coupon codes, prices or links.",
  "inputSchema": {
    "type": "object",
    "required": ["calendar_id", "doors"],
    "properties": {
      "calendar_id": { "type": "string" },
      "doors": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "required": ["day", "content_type"],
          "properties": {
            "day": { "type": "integer", "minimum": 1, "maximum": 50 },
            "content_type": { "type": "string", "enum": ["text", "embed", "link", "image", "video", "coupon", "quiz", "product", "event", "giveaway", "download", "survey", "music"] },
            "title": { "type": "string", "maxLength": 255 },
            "text": { "type": "string" },
            "url": { "type": "string", "format": "uri" },
            "coupon_code": { "type": "string", "maxLength": 64 },
            "data": { "type": "object", "description": "Type specific fields: options, answer, price, date, time, location, prize, deadline, button, artist" },
            "media_id": { "type": "string" }
          }
        }
      },
      "overwrite": { "type": "boolean", "default": false }
    }
  },
  "annotations": { "readOnlyHint": false, "idempotentHint": true }
}

Tool-Ergebnisse

Ergebnisse enthalten einen kurzen Text, den der Assistent weitergeben kann, einen Link auf die betroffene Ressource und structuredContent mit den genauen Zahlen, damit der Assistent nicht aus Fließtext raten muss.

{
  "content": [
    {
      "type": "text",
      "text": "Saved 24 doors in \"Northwind Coffee Advent Calendar\". Door 1 opens on 1 December 2026 at 08:00 (Europe/Berlin). Public link: https://adventskalendererstellen.de/c/k7x2mq9t/"
    },
    { "type": "resource_link", "uri": "calendar://cal_4Hq8nW2kLp", "name": "Calendar", "mimeType": "application/json" }
  ],
  "structuredContent": {
    "calendar_id": "cal_4Hq8nW2kLp",
    "doors_written": 24,
    "doors_skipped": 0,
    "doors_filled": 24,
    "door_count": 24
  },
  "isError": false
}

Ressourcen

Neben Tools bietet der Server Ressourcen an, die ein Client als Kontext in die Unterhaltung laden kann, zum Beispiel um einen bestehenden Kalender zu besprechen, bevor er geändert wird.

calendar://{id}                  calendar settings and public link
calendar://{id}/doors            all doors with unlock times and content
calendar://{id}/doors/{day}      a single door
stats://{id}                     views, door opens, clicks, entries
backgrounds://catalog            background designs, styles and tags

Prompts

Der Server bringt fertige Prompts mit, die Clients als Befehle anzeigen. Sie führen den Assistenten durch die richtigen Fragen, bevor er etwas anlegt.

• plan_marketing_calendar: Kundenkalender mit einem Angebot pro Türchen, für Shops und Marken.
• plan_team_calendar: Kalender für Kolleginnen und Kollegen mit Grüßen, Quizfragen und kleinen Überraschungen.
• plan_family_calendar: persönlicher Kalender mit Nachrichten, Fotos und Videos für einen lieben Menschen.
• review_calendar: prüft einen bestehenden Kalender auf leere Türchen, defekte Links und Türchen, die sich an einem Wochenende öffnen, wenn das Büro geschlossen ist.

{
  "name": "plan_marketing_calendar",
  "description": "Plans a customer advent calendar with one offer per door and fills it after approval.",
  "arguments": [
    { "name": "brand", "required": true },
    { "name": "door_count", "description": "usually 24", "required": false },
    { "name": "offers", "description": "list of offers or products to feature", "required": false }
  ]
}

Beispielgespräch

Eine Kaffeerösterei baut mit Claude einen Newsletter-Kalender. Tool-Aufrufe stehen in eckigen Klammern.

User:  We are a small coffee roaster. I want an advent calendar for our
       newsletter, 24 doors, a new discount every morning at 8.

Agent: [list_options] Sounds good. Which products should the doors feature,
       and do you already have coupon codes in your shop system?

User:  Filter coffee, espresso, the winter blend and our grinder. Codes are
       ADVENT01 to ADVENT24, all 15 % off, door 24 is 30 %.

Agent: [create_calendar: 2026-12-01 to 2026-12-24, 08:00, Europe/Berlin,
        template_style=cozy]
       Here is my plan for the 24 doors: ... Shall I fill them like this?

User:  Yes, but door 6 should be a video from our roastery instead.

Agent: [fill_doors: 23 coupon doors]
       [set_door: day=6, content_type=embed, url=https://youtu.be/...]
       Done. All 24 doors are filled, door 1 opens on 1 December at 08:00.
       Link for the newsletter: https://adventskalendererstellen.de/c/k7x2mq9t/

Was der Assistent nicht tut

• Er erfindet keine Gutscheincodes, Preise, Links oder Rechtstexte. Fehlt Inhalt, fragt er dich.
• Er zeigt dir den Plan für alle Türchen, bevor er sie füllt, und überschreibt keine Türchen mit Inhalt, wenn du nicht zustimmst.
• Er löscht keine Kalender und ändert weder deinen Tarif noch deine Zahlungsdaten.
• Er setzt kein Passwort und keinen Tracking-Code, wenn du ihm keinen gibst.
• Er sieht nie Daten deiner Besucher, nur die aggregierten Zahlen aus get_stats.

Diese Regeln stehen in den Tool-Beschreibungen und werden zusätzlich vom Server durchgesetzt: fill_doors ohne overwrite: true überspringt bereits gefüllte Türchen, und ein Tool zum Löschen existiert nicht.

Scopes

Auf Anfrage stellen wir einen Schlüssel mit weniger Rechten aus, zum Beispiel für einen Assistenten, der nur Zahlen berichten soll.

Tools außerhalb des Scopes des Schlüssels werden dem Client gar nicht erst aufgelistet.

Fehler

Schlägt ein Tool-Aufruf fehl, hat das Ergebnis isError: true und einen Text, der dem Assistenten sagt, was schiefgegangen ist und was er als Nächstes tun kann. So kann er sich selbst korrigieren oder dich fragen, statt aufzugeben.

{
  "content": [
    {
      "type": "text",
      "text": "Door 25 does not exist: this calendar runs from 2026-12-01 to 2026-12-24 and has 24 doors. Ask the user whether to extend end_date with update_calendar (up to 50 doors) or to drop door 25."
    }
  ],
  "isError": true
}

Tarifgrenzen kommen auf dieselbe Weise zurück: Der Text nennt den nötigen Tarif und bittet den Assistenten, es dir zu sagen.

Limits

Tool-Aufrufe zählen gegen dasselbe Rate-Limit wie die API (120 Anfragen pro Minute und Schlüssel); fill_doors zählt als ein Aufruf. Medien aus add_media_from_url unterliegen denselben Größenlimits: Bilder bis 2 MB, Videos bis 20 MB, Audiodateien und Downloads bis 10 MB.

Datenschutz

Der MCP-Server speichert nichts von deiner Unterhaltung. Er erhält nur die Tool-Aufrufe und ihre Argumente, genau wie bei einer API-Anfrage, und führt Request-Logs 30 Tage lang für den Support.

Was dein Assistent mit den Ergebnissen macht, hängt von seinem Anbieter ab. Sind Türchen-Inhalte vertraulich, prüfe die Datenschutzeinstellungen deines KI-Clients.

Support

Wenn sich dein Client nicht verbindet oder ein Tool anders funktioniert als beschrieben, schreib an [email protected] mit dem Namen des Clients, dem Tool und der Uhrzeit. Wir lesen jede Nachricht.