De MCP-server hangt LiedMaker rechtstreeks in AI-agenten. Claude, Cursor of een eigen agent kan midden in een gesprek een lied laten schrijven en produceren, zonder dat iemand met de hand een REST-aanvraag bouwt.
Bijgewerkt: 2026-09-16
Sleutels worden handmatig uitgegeven. Een korte mail met je plan, verwacht volume en talen is genoeg, en de vrijgave duurt meestal één werkdag.
Het Model Context Protocol is een open standaard voor de manier waarop een AI-agent externe tools en gegevens bereikt. In plaats van een API-client te schrijven, zet je de server eenmalig in de configuratie van de agent. Daarna kent het model de beschikbare tools en roept het ze zelf aan als het gesprek daarom vraagt.
Onze server biedt dezelfde mogelijkheden als de REST-API: een lied laten schrijven en produceren, de stand opvragen, de songtekst halen, opnieuw laten genereren, een betaallink maken. Het verschil zit in de vorm. De toolbeschrijvingen zijn zo geschreven dat een model begrijpt wanneer een lied überhaupt zinvol is en welke gegevens het vooraf moet verzamelen.
Het adres is https://mcp.liedmaker.nl/mcp. Het is dezelfde dienst als op /api/, alleen in een andere jas, en hij gebruikt dezelfde sleutels. Wie beide naast elkaar draait, ziet in beide werelden dezelfde liedjes.
Ook hier wordt alleen per afgerond lied afgerekend, momenteel 29,99 €. Toolaanroepen die alleen lezen of iets voorbereiden, kosten niets.
De weg is dezelfde als bij de REST-API: sleutels worden met de hand uitgegeven. Schrijf naar songs@maxkuch.com en vertel kort welke agent je wilt aansluiten, wat die moet doen en op welk volume je rekent.
Je krijgt een testsleutel (sk_test_) en een livesleutel (sk_live_). Wie al een API-sleutel heeft, heeft geen tweede nodig: dezelfde sleutel opent de MCP-server.
Voor teams die de server aan meerdere mensen willen geven, geven we op verzoek meerdere sleutels met gezamenlijke afrekening uit. Dan is achteraf te zien welke sleutel welk lied heeft gemaakt.
De server spreekt MCP over HTTP met server-sent events voor de terugweg, oftewel het transport dat de huidige clients standaard gebruiken. Een lokaal proces is niet nodig, er valt niets te installeren.
De authenticatie loopt via dezelfde Authorization-header als bij de REST-API: Authorization: Bearer sk_live_.... Clients die alleen stdio kunnen, bereiken de server via mcp-remote als brug, zie de configuratie voor Claude Desktop hieronder.
Client en server onderhandelen de protocolversie bij het opzetten van de verbinding. Wij ondersteunen de actuele versie en de versie daarvoor, zodat een client-update nooit tot een harde breuk leidt.
curl https://mcp.liedmaker.nl/healthIn Claude Code volstaat één commando. De sleutel komt bij voorkeur uit een omgevingsvariabele en niet uit het klembord.
claude mcp add --transport http songs \
https://mcp.liedmaker.nl/mcp \
--header "Authorization: Bearer $SONG_API_KEY"Claude Desktop leest zijn serverlijst uit claude_desktop_config.json. De regel slaat via mcp-remote een brug naar het HTTP-transport.
{
"mcpServers": {
"songs": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.liedmaker.nl/mcp",
"--header", "Authorization: Bearer ${SONG_API_KEY}"],
"env": { "SONG_API_KEY": "sk_live_..." }
}
}
}Cursor, Windsurf, Zed en de meeste andere clients nemen de server-URL rechtstreeks aan en staan eigen headers toe. Daarmee vervalt de brug.
{
"mcpServers": {
"songs": {
"url": "https://mcp.liedmaker.nl/mcp",
"headers": { "Authorization": "Bearer sk_live_..." }
}
}
}Na het toevoegen zou de client zeven tools moeten tonen. Blijft de lijst leeg, dan ligt het bijna altijd aan de header: een verlopen of verkeerd gekopieerde sleutel levert een lege toollijst op in plaats van een zichtbare foutmelding.
De server biedt zeven tools. Schrijvende tools zijn als zodanig gemarkeerd, zodat clients er desgewenst om bevestiging kunnen vragen.
| Tool | Soort | Beschrijving |
|---|---|---|
| create_song | Schrijft en produceert een lied. Keert meteen terug met een lied-id, de opname volgt enkele minuten later. Desgewenst blokkeert de aanroep tot de preview klaar is. | |
| get_song | Geeft de actuele stand van een lied met status, previewlink en betaalstatus. | |
| list_songs | Somt de laatst gemaakte liedjes op, eventueel gefilterd op status. Handig als de agent na een pauze de draad weer oppakt. | |
| get_lyrics | Geeft de volledige songtekst als tekst terug. De tekst is altijd gratis, ook voor de betaling. | |
| regenerate_song | Maakt een nieuwe versie, met dezelfde tekst en een nieuwe opname of helemaal opnieuw. Tot drie keer per lied, zonder extra kosten. | |
| get_checkout_link | Maakt een betaallink voor een lied en geeft die als URL terug, zodat de agent hem in het gesprek kan doorgeven. | |
| list_options | Noemt de geldige waarden voor gelegenheid, stemming, stem en taal. Agenten kunnen dat beter één keer per sessie opvragen dan waarden raden. |
Lezende tools zijn idempotent en mogen zonder overleg worden aangeroepen. create_song en regenerate_song veranderen de toestand en veroorzaken productiekosten, daarom melden ze zich bij de client als schrijvend.
De belangrijkste tool is create_song. Het schema is bewust smal: drie verplichte velden, de rest optioneel met zinnige standaardwaarden. Hoe minder een model hoeft te beslissen, hoe minder vaak het waarden verzint.
{
"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": "nl" },
"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." }
}
}
}De hefboom is details. Daar horen concrete dingen: bijnamen, gedeelde ervaringen, eigenaardigheden, lopende grappen. Een lied uit drie bijvoeglijke naamwoorden klinkt als drie bijvoeglijke naamwoorden. Veertig tekens zijn het minimum, en de beschrijving van de tool zegt het model uitdrukkelijk dat het moet doorvragen in plaats van details te verzinnen.
Het veld wait regelt de omgang met de wachttijd. Standaard is false: de aanroep keert meteen terug, de agent kan doorpraten en later get_song aanroepen. Met true blokkeert de aanroep tot de preview van 45 seconden er is, hoogstens tien minuten. Voor gespreksagenten is false bijna altijd de betere keuze.
Zonder language zingt het lied in nl, de taal van dit domein. Alle gangbare Europese talen en Japans zijn mogelijk, de geldige lijst levert list_options.
Tools antwoorden op twee sporen: een tekstblok voor het model en, waar het helpt, structuredContent voor de client. Het tekstblok is zo geformuleerd dat het model het de gebruiker direct kan voorlezen zonder het te vertalen.
{
"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.liedmaker.nl/preview/sng_3n8Kd2ZpQv.mp3",
"paid": false
},
"isError": false
}Songtekst en audio komen terug als verwijzingen naar resources, niet als ingesloten data. Een client die audio kan afspelen, lost de verwijzing op. Een client die dat niet kan, negeert hem en houdt de tekst. Zo belandt er nooit een MP3 in het contextvenster.
Betaalde liedjes dragen in structuredContent bovendien audio_url met de volledige opname. De link is 24 uur geldig en kan op elk moment via get_song worden ververst.
Naast tools biedt de server resources onder het schema song://. Clients die resources ondersteunen, kunnen ze tonen of aan het model hangen zonder een tool aan te roepen.
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 paymentDe lijst met beschikbare resources verandert tijdens de sessie zodra er nieuwe liedjes ontstaan. De server stuurt in dat geval een wijzigingsmelding, zodat clients hun lijst kunnen bijwerken.
De resource audio bestaat pas na de betaling. Een aanroep daarvoor is technisch geen fout, maar geeft een melding met de betaallink terug.
Voor de meest voorkomende gelegenheden liggen kant-en-klare prompts klaar. Ze verzamelen de gegevens die een goed lied nodig heeft en roepen daarna create_song aan. In clients die prompts ondersteunen, verschijnen ze als snelcommando’s.
{
"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 }
]
}Beschikbaar zijn nu birthday_song, wedding_song, farewell_song en christmas_song. Wie een eigen verloop verkiest, negeert de prompts en roept de tools direct aan.
Zo ziet het in de praktijk uit. De agent verzamelt details, roept de tool aan, levert tekst en preview en neemt correcties aan.
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.Opmerkelijk is de tweede stap: opnieuw genereren kost niets en duurt weer een paar minuten. Precies daarvoor is de preview er, en agenten zouden die actief moeten aanbieden in plaats van de eerste versie als definitief te behandelen.
Een agent kan geen betaling starten. Hij kan alleen een betaallink maken en doorgeven, betaald wordt er in de browser. Dat is bewust zo gebouwd: een model hoort geen koopbeslissing te nemen die een mens niet heeft gezien.
get_checkout_link levert een URL die 24 uur geldig is. Na de betaling gaat het lied naar de status complete, en bij de volgende get_song ligt de volledige opname klaar. De agent hoeft nergens op te abonneren, een latere aanroep volstaat.
Wie de betaling in het eigen systeem afhandelt en alleen met ons afrekent, krijgt op verzoek de directe weg uit de REST-API vrijgegeven. Dan vervalt de betaallink en wordt het lied meteen vrijgegeven.
Elke sleutel draagt rechten. Standaard is lezen en schrijven zonder toegang tot de afrekening, wat voor de meeste agenten past.
| Recht | Naam | Betekenis |
|---|---|---|
| songs:read | Liedjes opvragen, opsommen, songteksten lezen. Zonder dit recht meldt de server een lege toollijst. | |
| songs:write | Liedjes maken en opnieuw genereren. Veroorzaakt productiekosten. | |
| billing | Betaallinks maken en de betaalstatus lezen. Alleen nodig als de agent links moet doorgeven. |
Tools waarvoor het recht ontbreekt, verschijnen helemaal niet in de toollijst. Dat is prettiger dan een foutmelding midden in het gesprek, omdat het model dan niets aanbiedt wat het toch niet kan.
Fouten komen terug als een gewoon toolresultaat met isError: true, niet als protocolfout. De tekst is aan het model gericht en zegt wat er moet gebeuren, zodat de agent in het gesprek zinvol kan reageren.
{
"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.liedmaker.nl/c/cs_live_8Hd2Kq..." }
],
"isError": true
}Echte protocolfouten komen alleen voor bij een ongeldige sleutel, een ontbrekend recht of een kapotte aanvraag. Alles wat inhoudelijk mis kan gaan, dus ontbrekende gegevens, een onbetaald lied of een bereikte limiet, komt als tekst terug.
Producties die blijven hangen, gaan na 15 minuten naar de status failed en kosten niets. De agent kan daarna gewoon opnieuw aanroepen.
Dezelfde limieten gelden als in de REST-API: 60 toolaanroepen per minuut per sleutel, hoogstens tien gelijktijdige producties, tot drie nieuwe generaties per lied. Voor hogere waarden volstaat een mail.
Een overschreden limiet leidt niet tot een harde fout, maar tot een tekstresultaat met de melding wanneer het weer verdergaat. Agenten kunnen dan beter wachten dan meteen opnieuw aanroepen.
Liedjes blijven 90 dagen opvraagbaar. Daarna verdwijnen ze met de ingevoerde gegevens, en get_song meldt ze als onbekend.
De gegevens uit details gaan uitsluitend naar de productie van dat ene lied. Wij trainen er geen eigen modellen mee. Een lied laat zich altijd eerder wissen, daarvoor is er in de REST-API DELETE /v1/songs/{id}.
Op het afgeronde lied krijg je een niet-exclusief, uitdrukkelijk commercieel gebruiksrecht. Of op een door AI gemaakte opname een eigen auteursrecht ontstaat, is in veel rechtsstelsels nog niet uitgemaakt. Wie daarvan afhankelijk is, laat dat beter vooraf toetsen.
Geeft je agent gegevens van je klanten aan ons door, dan ben jij verwerkingsverantwoordelijke en zijn wij verwerker. Een verwerkersovereenkomst krijg je op aanvraag.
De server draait op dezelfde infrastructuur als de REST-API. Onderhoudsvensters kondigen we per mail aan op het opgegeven adres, en wijzigingen aan toolschema’s zijn uitsluitend toevoegingen.
Komt er een nieuwe tool bij, dan stuurt de server een wijzigingsmelding. Clients die daarop reageren, zien hem zonder herstart. Bestaande tools houden hun naam en hun verplichte velden.
Vragen, hogere limieten, eigen prompts of tools voor een specifiek verloop: songs@maxkuch.com. Noem bij technische problemen het lied-id, dan vinden we de aanvraag meteen.
Wie liever rechtstreeks tegen HTTP werkt, vindt dezelfde mogelijkheden als REST-interface op /api/. Beide wegen delen sleutels, limieten en afrekening.
Sleutels worden handmatig uitgegeven. Een korte mail met je plan, verwacht volume en talen is genoeg, en de vrijgave duurt meestal één werkdag.