MCP-server

Innledning

Model Context Protocol er den åpne standarden KI-assistenter snakker med eksterne systemer gjennom. Serveren vår eksponerer hele sangproduksjonen som MCP-verktøy: agenten kan lage en sang, følge status, hente tekst og lyd og starte en ny generering.

Fordelen mot REST-API-et er samtalen. En agent vet hvilke detaljer som mangler for at sangen skal bli personlig, og spør etter dem selv. Brukeren forteller om faren sin, agenten lager en brief av det og bestiller sangen.

Serveren kjører på https://mcp.lagsang.com og snakker HTTP med Server-Sent Events, transporten alle aktuelle klienter støtter. Den bruker de samme nøklene som REST-API-et, så den som allerede integrerer trenger ingen nye opplysninger.

Tilgang

Nøkler deles ut for hånd, som for REST-API-et. Skriv til songs@maxkuch.com og nevn hva du vil bygge, forventet volum og språk. Frigivelsen tar normalt én virkedag.

Du får en testnøkkel med prefikset sk_test_ og en livenøkkel med prefikset sk_live_. Med testnøkkelen virker alle verktøy likt, men ingen ekte produksjon starter og ingenting koster.

Den som allerede har en API-nøkkel trenger ikke mer: den samme nøkkelen åpner MCP-serveren.

Tilkobling

Serveradressen er https://mcp.lagsang.com/sse. Autentiseringen skjer med et bearer-token i Authorization-headeren, nøyaktig som i REST-API-et.

Serveren følger protokollversjon 2026-03-26 og melder om evnene sine under håndtrykket: verktøy, ressurser og prompter. Klienter som bare kjenner eldre versjoner er fortsatt kompatible, bare uten promptene.

curl https://mcp.lagsang.com/health

Oppsett i klienter

Nesten alle MCP-klienter settes opp med en liten JSON-fil. Her er de tre vanligste variantene, hver med nøkkelen på rett sted.

Claude Code

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

Claude Desktop

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

Cursor

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

Etter omstart av klienten dukker verktøyene opp i listen. Gjør de ikke det, skyldes det nesten alltid en manglende nøkkel eller en JSON med syntaksfeil.

Verktøy

Serveren stiller sju verktøy til rådighet. De er bevisst få og tydelig navngitt, slik at en agent velger riktig.

Bare create_song og regenerate_song endrer noe. Klienter som spør før skrivende operasjoner, spør altså nøyaktig ved disse to.

create_song i detalj

Dette er det sentrale verktøyet. Skjemaet er bevisst utførlig, slik at agenten vet hvilke opplysninger den må skaffe først.

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

Feltet details er det avgjørende. Skjemabeskrivelsen sier tydelig til agenten at det trengs konkrete detaljer, ikke adjektiver. En god agent spør ikke "hvordan er faren din", men "hva sier han alltid når noe irriterer ham".

{
  "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.lagsang.com/preview/sng_3n8Kd2ZpQv.mp3",
    "paid": false
  },
  "isError": false
}

Svaret inneholder tekst for agenten og strukturerte data for koden. Kallet returnerer med én gang, produksjonen fortsetter i bakgrunnen.

Svarenes form

Hvert verktøy leverer to ting: en lesbar tekstblokk som agenten kan gjengi direkte, og structuredContent med de samme opplysningene i maskinlesbar form. En agent kan altså svare brukeren uten å miste identifikatorene.

Sangidentifikatorene er de samme som i REST-API-et. En sang laget via MCP kan senere hentes via REST og omvendt, noe som er praktisk når agenten samler briefen og backend-en din håndterer leveringen.

Ressurser

I tillegg til verktøyene tilbyr serveren ressurser, altså innhold kun til lesing som en klient kan laste inn i konteksten sin uten å kalle et verktøy.

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

song://options inneholder alle gyldige verdier, song://guide/details en kort veiledning om hva som gjør en sang personlig, song://songs/{id} en enkelt sang med tekst og status. Veiledningen er særlig ment for agenter: den gjør det vesentlig mer sannsynlig at de spør om det riktige.

Prompter

Serveren har ferdige prompter med seg som en klient kan tilby som kommandoer. De sparer brukeren for forklaringen av hva han skal fortelle.

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

gather_song_details leder agenten gjennom en kort samtale som ender i en brukbar brief. write_song_brief gjør en eksisterende tekst, for eksempel en kundeepost, om til en strukturert brief. suggest_occasion hjelper når anledningen ikke passer inn i de vanlige kategoriene.

En typisk samtale

Slik ser det ut i praksis, med en bruker som ennå ikke helt vet hva han vil.

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.

Poenget ligger i midten. Agenten nøyer seg ikke med den første generelle beskrivelsen, men spør to ganger til, og det er nettopp de to spørsmålene som gjør en sang om hvem som helst til en sang om denne personen.

Betaling

En agent kan ikke utløse en betaling. Den kan bare lage en betalingslenke og sende den videre, betalingen skjer i nettleseren. Det er bygget slik med vilje: en modell skal ikke ta en kjøpsbeslutning et menneske ikke har sett.

get_checkout_link gir en URL som gjelder i 24 timer. Etter betalingen går sangen over i status complete, og ved neste get_song ligger hele opptaket klart. Agenten trenger ikke abonnere på noe, et senere kall holder.

Den som håndterer betalingen i eget system og bare fakturerer oss, kan få den direkte veien i REST-API-et åpnet på forespørsel. Da faller betalingslenken bort og sangen frigis med en gang.

Rettigheter og scope

Hver nøkkel bærer tillatelser. Standard er lesing og skriving uten tilgang til fakturering, noe som passer for de fleste agenter.

Verktøy der tillatelsen mangler, dukker ikke opp i verktøylisten i det hele tatt. Det er hyggeligere enn en feilmelding midt i samtalen, fordi modellen da ikke tilbyr noe den likevel ikke kan.

Feil

Feil kommer som verktøyresultat med isError: true og en forståelig tekst, ikke som protokollfeil. Slik kan agenten reagere og forklare brukeren hva som mangler, i stedet for å avbryte.

{
  "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.lagsang.com/c/cs_live_8Hd2Kq..." }
  ],
  "isError": true
}

Feilkodene tilsvarer REST-API-ets: validation_error, rate_limit, not_found, permission_error, api_error. Teksten er formulert slik at en agent kan gjengi den ordrett.

Grenser

De samme grensene gjelder som for REST-API-et: 60 verktøykall per minutt og nøkkel samt ti samtidige produksjoner. Flere kall havner i kø i stedet for å mislykkes.

En MCP-økt står åpen så lenge klienten holder den. Etter 30 minutters inaktivitet lukker vi forbindelsen; enhver aktuell klient kobler seg til igjen av seg selv.

Vokser volumet, skriv til oss så hever vi grensene.

Data

Det agenten sender oss bruker vi til å produsere akkurat den sangen og til ingenting annet. Ingen trening av egne modeller på brukernes innhold.

Inndata og ferdige sanger blir liggende i 90 dager, deretter slettes de. For tidligere sletting finnes DELETE /v1/songs/{id} i REST-API-et.

Minn brukerne om at de forteller private ting om virkelige personer. En agent bør spørre etter konkrete detaljer uten å styre mot sensitive helse- eller økonomiopplysninger.

Drift

MCP-serveren kjører på den samme infrastrukturen som REST-API-et. Det finnes ingen egen komponent å installere eller oppdatere: vi legger til nye verktøy additivt, de eksisterende forblir stabile.

En klient bør lese verktøylisten ved oppstart i stedet for å skrive den inn i koden. Det er den vanlige måten og gir deg nyhetene uten endringer.

Ved planlagt vedlikehold varsler vi aktive kontoer på e-post minst 48 timer i forveien. Så langt har det ikke vært planlagte stopp.

Support

Spørsmål om oppsett, scopes, høyere grenser eller særlige tilfeller: songs@maxkuch.com. Ved tekniske problemer, oppgi verktøyets navn og omtrentlig tidspunkt for kallet.

Den som heller vil integrere direkte enn å gå via en agent, finner REST-API-et på /api/. Begge veier bruker de samme nøklene og de samme identifikatorene.