MCP-Server

Einfuehrung

Das Model Context Protocol ist ein offener Standard dafuer, wie ein KI-Agent externe Werkzeuge und Daten anspricht. Statt einen API-Client zu schreiben, traegt man den Server einmal in die Konfiguration des Agenten ein. Danach kennt das Modell die verfuegbaren Werkzeuge und ruft sie selbst auf, wenn das Gespraech es hergibt.

Unser Server bildet dieselben Faehigkeiten ab wie die REST-API: ein Lied schreiben und produzieren lassen, den Stand abfragen, den Liedtext holen, neu generieren lassen, einen Bezahllink erzeugen. Der Unterschied liegt im Zuschnitt. Die Werkzeugbeschreibungen sind so formuliert, dass ein Modell versteht, wann ein Lied ueberhaupt sinnvoll ist und welche Angaben es vorher einsammeln sollte.

Die Adresse lautet https://mcp.liederstellen.ch/mcp. Es ist derselbe Dienst wie unter /api/, nur mit einer anderen Huelle, und er benutzt dieselben Schluessel. Wer beides parallel betreibt, sieht dieselben Lieder in beiden Welten.

Zugang

Es gilt derselbe Weg wie bei der REST-API: Schluessel werden von Hand vergeben. Schreib an songs@maxkuch.com und nenne kurz, welchen Agenten du anbinden willst, was er tun soll und mit welchem Volumen zu rechnen ist.

Du bekommst einen Testschluessel (sk_test_) und einen Liveschluessel (sk_live_). Wer schon einen API-Schluessel hat, braucht keinen zweiten: derselbe Schluessel oeffnet den MCP-Server.

Fuer Teams, die den Server mehreren Personen zur Verfuegung stellen wollen, vergeben wir auf Wunsch mehrere Schluessel mit gemeinsamer Abrechnung. Dann laesst sich im Nachhinein sehen, welcher Schluessel welches Lied erzeugt hat.

Verbindung und Transport

Der Server spricht MCP ueber HTTP mit Server-Sent-Events fuer die Rueckrichtung, also den Transport, den die aktuellen Clients standardmaessig verwenden. Ein lokaler Prozess wird nicht gebraucht, es gibt nichts zu installieren.

Die Authentifizierung laeuft ueber denselben Authorization-Header wie bei der REST-API: Authorization: Bearer sk_live_.... Clients, die nur stdio koennen, erreichen den Server ueber mcp-remote als Bruecke, siehe die Konfiguration fuer Claude Desktop weiter unten.

Die Protokollversion verhandeln Client und Server beim Verbindungsaufbau. Wir unterstuetzen die jeweils aktuelle Fassung und die davor, damit ein Client-Update nie zu einem harten Bruch fuehrt.

curl https://mcp.liederstellen.ch/health

Einrichtung

In Claude Code genuegt ein Befehl. Der Schluessel sollte aus einer Umgebungsvariable kommen und nicht in der Zwischenablage landen.

claude mcp add --transport http songs \
  https://mcp.liederstellen.ch/mcp \
  --header "Authorization: Bearer $SONG_API_KEY"

Claude Desktop

Claude Desktop liest seine Serverliste aus claude_desktop_config.json. Der Eintrag brueckt ueber mcp-remote auf den HTTP-Transport.

{
  "mcpServers": {
    "songs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.liederstellen.ch/mcp",
               "--header", "Authorization: Bearer ${SONG_API_KEY}"],
      "env": { "SONG_API_KEY": "sk_live_..." }
    }
  }
}

Cursor und andere Clients

Cursor, Windsurf, Zed und die meisten anderen Clients nehmen die Server-URL direkt entgegen und erlauben eigene Header. Damit entfaellt die Bruecke.

{
  "mcpServers": {
    "songs": {
      "url": "https://mcp.liederstellen.ch/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Nach dem Eintragen sollte der Client sieben Werkzeuge anzeigen. Taucht die Liste nicht auf, liegt es fast immer am Header: ein abgelaufener oder falsch kopierter Schluessel fuehrt zu einer leeren Werkzeugliste statt zu einer sichtbaren Fehlermeldung.

Werkzeuge

Der Server stellt sieben Werkzeuge bereit. Schreibende Werkzeuge sind als solche markiert, damit Clients sie bei Bedarf bestaetigen lassen koennen.

Lesende Werkzeuge sind idempotent und duerfen vom Agenten ohne Rueckfrage aufgerufen werden. create_song und regenerate_song veraendern den Zustand und loesen Produktionskosten aus, deshalb melden sie sich beim Client als schreibend an.

create_song im Detail

Das wichtigste Werkzeug ist create_song. Sein Schema ist bewusst schmal gehalten: drei Pflichtfelder, der Rest optional mit vernuenftigen Vorgaben. Je weniger ein Modell entscheiden muss, desto seltener erfindet es Werte.

{
  "name": "create_song",
  "description": "Write and produce a personalised song. Returns immediately with a song id; the recording is ready a few minutes later.",
  "inputSchema": {
    "type": "object",
    "required": ["occasion", "recipient_name", "details"],
    "properties": {
      "occasion":       { "type": "string", "enum": ["birthday", "wedding", "anniversary", "farewell", "funeral", "christening", "graduation", "christmas", "declaration", "other"] },
      "recipient_name": { "type": "string", "maxLength": 80 },
      "relationship":   { "type": "string", "maxLength": 80 },
      "language":       { "type": "string", "default": "de" },
      "mood":           { "type": "string", "enum": ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"] },
      "style":          { "type": "string" },
      "voice":          { "type": "string", "enum": ["female", "male", "duet", "choir", "childrens", "surprise_me"] },
      "details":        { "type": "string", "minLength": 40, "maxLength": 4000 },
      "wait":           { "type": "boolean", "default": false, "description": "Block until the preview is ready, at most 10 minutes." }
    }
  }
}

Der Hebel ist details. Dort gehoeren konkrete Dinge hinein: Spitznamen, gemeinsame Erlebnisse, Eigenheiten, laufende Witze. Ein Lied aus drei Adjektiven klingt nach drei Adjektiven. Mindestens vierzig Zeichen sind Pflicht, und die Beschreibung des Werkzeugs sagt dem Modell ausdruecklich, dass es nachfragen soll, statt Details zu erfinden.

Das Feld wait steuert den Umgang mit der Wartezeit. Standard ist false: der Aufruf kehrt sofort zurueck, der Agent kann weiterreden und spaeter get_song aufrufen. Mit true blockiert der Aufruf, bis die 45-Sekunden-Vorschau steht, hoechstens zehn Minuten. Fuer Gespraechsagenten ist false fast immer die bessere Wahl.

Ohne Angabe von language singt das Lied in de, der Sprache dieser Domain. Alle gaengigen europaeischen Sprachen und Japanisch sind moeglich, die gueltige Liste liefert list_options.

Antwortformat

Werkzeuge antworten zweigleisig: ein Textblock fuer das Modell und, wo sinnvoll, structuredContent fuer den Client. Der Textblock ist so formuliert, dass das Modell ihn dem Nutzer direkt vorlesen kann, ohne ihn zu uebersetzen.

{
  "content": [
    { "type": "text", "text": "Song sng_3n8Kd2ZpQv for Anna is written. Lyrics below, the 45 second preview is ready." },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/lyrics", "mimeType": "text/plain" } },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/preview", "mimeType": "audio/mpeg" } }
  ],
  "structuredContent": {
    "id": "sng_3n8Kd2ZpQv",
    "status": "preview_ready",
    "preview_url": "https://cdn.liederstellen.ch/preview/sng_3n8Kd2ZpQv.mp3",
    "paid": false
  },
  "isError": false
}

Liedtext und Audio kommen als Ressourcenverweise zurueck, nicht als eingebettete Daten. Ein Client, der Audio abspielen kann, loest den Verweis auf. Ein Client, der das nicht kann, ignoriert ihn und behaelt den Text. So wird nie eine MP3-Datei in das Kontextfenster geschrieben.

Bezahlte Lieder tragen in structuredContent zusaetzlich audio_url mit der vollstaendigen Aufnahme. Der Link ist 24 Stunden gueltig und laesst sich jederzeit ueber get_song erneuern.

Ressourcen

Neben Werkzeugen stellt der Server Ressourcen unter dem Schema song:// bereit. Clients, die Ressourcen unterstuetzen, koennen sie anzeigen oder an das Modell anhaengen, ohne ein Werkzeug aufzurufen.

song://sng_3n8Kd2ZpQv           the song object as JSON
song://sng_3n8Kd2ZpQv/lyrics    the full lyrics as plain text
song://sng_3n8Kd2ZpQv/preview   the first 45 seconds as audio/mpeg
song://sng_3n8Kd2ZpQv/audio     the full recording, only after payment

Die Liste der verfuegbaren Ressourcen aendert sich waehrend der Sitzung, sobald neue Lieder entstehen. Der Server schickt in diesem Fall eine Aenderungsmitteilung, sodass Clients ihre Liste aktualisieren koennen.

Die Ressource audio existiert erst nach der Bezahlung. Ein Zugriff davor ist kein Fehler im technischen Sinn, sondern liefert einen Hinweis samt Bezahllink zurueck.

Prompts

Fuer die haeufigsten Anlaesse liegen fertige Prompts bereit. Sie sammeln die Angaben ein, die ein gutes Lied braucht, und rufen danach create_song auf. In Clients, die Prompts unterstuetzen, erscheinen sie als Schnellbefehle.

{
  "name": "birthday_song",
  "description": "Collects the five things a birthday song needs and then creates it.",
  "arguments": [
    { "name": "recipient_name", "required": true },
    { "name": "age",            "required": false },
    { "name": "details",        "required": false }
  ]
}

Verfuegbar sind derzeit birthday_song, wedding_song, farewell_song und christmas_song. Wer eigene Ablaeufe bevorzugt, ignoriert die Prompts einfach und ruft die Werkzeuge direkt auf.

Beispielgespraech

So sieht der Ablauf in der Praxis aus. Der Agent sammelt Details, ruft das Werkzeug auf, liefert Text und Vorschau und nimmt Korrekturen entgegen.

User:  My sister Anna turns 34 on Friday. She climbs, she is always late,
       and she calls everyone chef. Make her a song.

Claude: [calls create_song with occasion=birthday, recipient_name=Anna,
        relationship=sister, mood=funny, details="climbs every weekend,
        always ten minutes late, calls everyone chef"]

        Done. Here are the lyrics, and the first 45 seconds are playable
        right away. Should the chorus lean more on the climbing or more
        on the chef thing?

User:  More chef.

Claude: [calls regenerate_song with keep_lyrics=false,
        note="put the chef running gag in the chorus"]

        New version is running, about five minutes.

Bemerkenswert ist der zweite Schritt: eine Neugenerierung kostet nichts und dauert wieder wenige Minuten. Genau dafuer ist die Vorschau da, und Agenten sollten sie aktiv anbieten, statt die erste Fassung als endgueltig zu behandeln.

Bezahlung

Ein Agent kann keine Zahlung ausloesen. Er kann nur einen Bezahllink erzeugen und weiterreichen, bezahlt wird im Browser. Das ist bewusst so gebaut: ein Modell soll keine Kaufentscheidung treffen, die ein Mensch nicht gesehen hat.

get_checkout_link liefert eine URL, die 24 Stunden gueltig ist. Nach der Zahlung wechselt das Lied in den Status complete, und beim naechsten get_song liegt die vollstaendige Aufnahme bereit. Der Agent muss nichts abonnieren, ein spaeterer Aufruf genuegt.

Wer die Bezahlung im eigenen System abwickelt und uns nur abrechnet, bekommt auf Anfrage den Direktweg aus der REST-API freigeschaltet. Dann entfaellt der Bezahllink und das Lied wird sofort freigegeben.

Berechtigungen

Jeder Schluessel traegt Berechtigungen. Standard ist Lesen und Schreiben ohne Abrechnungszugriff, was fuer die meisten Agenten passt.

Werkzeuge, fuer die die Berechtigung fehlt, tauchen in der Werkzeugliste gar nicht erst auf. Das ist angenehmer als eine Fehlermeldung mitten im Gespraech, weil das Modell dann nichts anbietet, was es ohnehin nicht kann.

Fehlerbehandlung

Fehler kommen als normales Werkzeugergebnis mit isError: true zurueck, nicht als Protokollfehler. Der Text ist an das Modell adressiert und sagt, was zu tun ist, damit der Agent im Gespraech sinnvoll reagieren kann.

{
  "content": [
    { "type": "text", "text": "The song is not paid for yet, so the full recording cannot be handed over. The checkout link is https://pay.liederstellen.ch/c/cs_live_8Hd2Kq..." }
  ],
  "isError": true
}

Echte Protokollfehler gibt es nur bei ungueltigem Schluessel, fehlender Berechtigung oder kaputter Anfrage. Alles, was fachlich schiefgehen kann, also fehlende Angaben, unbezahltes Lied, erreichtes Limit, kommt als Text zurueck.

Ausbleibende Produktionen laufen nach 15 Minuten in den Status failed und kosten nichts. Der Agent kann danach einfach erneut aufrufen.

Limits

Es gelten dieselben Limits wie in der REST-API: 60 Werkzeugaufrufe pro Minute je Schluessel, hoechstens zehn Produktionen gleichzeitig, bis zu drei Neugenerierungen je Lied. Fuer hoehere Werte reicht eine Mail.

Ein ueberschrittenes Limit fuehrt nicht zu einem harten Fehler, sondern zu einem Textergebnis mit dem Hinweis, wann es weitergeht. Agenten sollten dann warten statt sofort erneut aufzurufen.

Lieder bleiben 90 Tage abrufbar. Danach verschwinden sie samt Eingaben, und get_song meldet sie als unbekannt.

Daten und Rechte

Die Angaben aus details gehen ausschliesslich in die Produktion des jeweiligen Liedes. Wir trainieren damit keine eigenen Modelle. Ein Lied laesst sich jederzeit vorzeitig loeschen, dafuer gibt es in der REST-API DELETE /v1/songs/{id}.

Am fertigen Lied erhaeltst du ein nicht exklusives, ausdruecklich kommerzielles Nutzungsrecht. Zur Frage, ob an einer KI-erzeugten Aufnahme ein eigenes Urheberrecht entsteht, gibt es in vielen Rechtsordnungen noch keine abschliessende Klaerung. Wer darauf angewiesen ist, sollte das vorher pruefen lassen.

Wenn dein Agent Angaben deiner Kunden an uns weitergibt, bist du dafuer der Verantwortliche und wir der Auftragsverarbeiter. Einen Auftragsverarbeitungsvertrag bekommst du auf Anfrage.

Betrieb

Der Server laeuft auf derselben Infrastruktur wie die REST-API. Wartungsfenster kuendigen wir per Mail an die hinterlegte Adresse an, Aenderungen an Werkzeugschemata sind ausschliesslich additiv.

Kommt ein neues Werkzeug hinzu, schickt der Server eine Aenderungsmitteilung. Clients, die darauf reagieren, sehen es ohne Neustart. Bestehende Werkzeuge behalten ihre Namen und ihre Pflichtfelder.

Support

Fragen, hoehere Limits, eigene Prompts oder Werkzeuge fuer einen speziellen Ablauf: songs@maxkuch.com. Nenne bei technischen Problemen die Lied-ID, dann finden wir den Vorgang sofort.

Wer lieber direkt gegen HTTP arbeitet, findet dieselben Faehigkeiten als REST-Schnittstelle unter /api/. Beide Wege teilen sich Schluessel, Limits und Abrechnung.