MCP-palvelimemme antaa tekoälyavustajille suoran pääsyn laulutuotantoon. Agentti kerää yksityiskohdat keskustelussa, tilaa laulun ja toimittaa tuloksen, etkä kirjoita riviäkään koodia.
Päivitetty: 2026-09-16
Avaimet jaetaan käsin. Lyhyt viesti hankkeestasi, arvioidusta määrästä ja kielistä riittää, ja avaus vie yleensä yhden arkipäivän.
Model Context Protocol on avoin standardi, jolla tekoälyavustajat puhuvat ulkoisten järjestelmien kanssa. Palvelimemme tarjoaa koko laulutuotannon MCP-työkaluina: agentti voi luoda laulun, tarkistaa tilan, hakea sanoituksen ja äänen sekä käynnistää uudelleenluonnin.
Etu REST-rajapintaan nähden on keskustelu. Agentti tietää, mitä yksityiskohtia puuttuu, jotta laulusta tulee henkilökohtainen, ja kysyy niitä itse. Käyttäjä kertoo isästään, agentti tekee siitä toimeksiannon ja tilaa laulun.
Palvelin on osoitteessa https://mcp.tekoalylaulu.fi ja puhuu HTTP:tä Server-Sent Eventsin kanssa, eli kuljetuksella jota jokainen nykyinen asiakas tukee. Se käyttää samoja avaimia kuin REST-rajapinta, joten jo integroineen ei tarvitse uusia tunnuksia.
Myös MCP:n kautta laskutamme valmiista laulusta, tällä hetkellä 24,99 €. Sanoitus ja 45 sekunnin esikuuntelu pysyvät maksuttomina.
Avaimet jaetaan käsin, samoin kuin REST-rajapinnassa. Kirjoita osoitteeseen songs@maxkuch.com ja kerro, mitä olet rakentamassa, minkä määrän odotat ja millä kielillä. Avaus vie yleensä yhden arkipäivän.
Saat testiavaimen etuliitteellä sk_test_ ja tuotantoavaimen etuliitteellä sk_live_. Testiavaimella kaikki työkalut toimivat samoin, mutta oikeaa tuotantoa ei käynnisty eikä mikään maksa.
Jos sinulla on jo API-avain, muuta ei tarvita: sama avain avaa MCP-palvelimen.
Palvelimen osoite on https://mcp.tekoalylaulu.fi/sse. Tunnistautuminen tapahtuu bearer-tunnisteella Authorization-otsakkeessa, täsmälleen kuten REST-rajapinnassa.
Palvelin toteuttaa protokollaversion 2026-03-26 ja ilmoittaa kykynsä kättelyssä: työkalut, resurssit ja kehotteet. Vain vanhemmat versiot tuntevat asiakkaat pysyvät yhteensopivina, ilman kehotteita.
curl https://mcp.tekoalylaulu.fi/healthLähes jokainen MCP-asiakas asetetaan pienellä JSON-tiedostolla. Alla kolme yleisintä muunnelmaa, jokaisessa avain oikeassa kohdassa.
claude mcp add --transport http songs \
https://mcp.tekoalylaulu.fi/mcp \
--header "Authorization: Bearer $SONG_API_KEY"{
"mcpServers": {
"songs": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.tekoalylaulu.fi/mcp",
"--header", "Authorization: Bearer ${SONG_API_KEY}"],
"env": { "SONG_API_KEY": "sk_live_..." }
}
}
}{
"mcpServers": {
"songs": {
"url": "https://mcp.tekoalylaulu.fi/mcp",
"headers": { "Authorization": "Bearer sk_live_..." }
}
}
}Asiakkaan uudelleenkäynnistyksen jälkeen työkalut näkyvät listalla. Jos ne eivät näy, syy on lähes aina puuttuva avain tai JSON, jossa on syntaksivirhe.
Palvelin tarjoaa seitsemän työkalua. Niitä on tietoisesti vähän ja ne on nimetty selvästi, jotta agentti valitsee oikein.
| Työkalu | Kirjoittaa | Mihin se on |
|---|---|---|
| create_song | Tilaa uuden laulun. Tilaisuus, nimi ja yksityiskohdat ovat pakollisia. | |
| get_song | Palauttaa nykyisen tilan, sanoituksen ja saatavilla olevat linkit. | |
| list_songs | Listaa tilin viimeisimmät laulut, suodatus tilan mukaan. | |
| get_lyrics | Palauttaa koko sanoituksen tavallisena tekstinä. | |
| regenerate_song | Käynnistää maksuttoman uudelleenluonnin, vapaaehtoisella ohjeella. | |
| get_checkout_link | Luo laululle maksulinkin ja palauttaa sen URL-osoitteena, jotta agentti voi välittää sen keskustelussa. | |
| list_options | Palauttaa sallitut arvot tilaisuudelle, tunnelmalle, tyylille, äänelle ja kielelle. |
Vain create_song ja regenerate_song muuttavat jotain. Asiakkaat, jotka kysyvät ennen kirjoittavia toimenpiteitä, kysyvät siis juuri näissä kahdessa.
Tämä on keskeinen työkalu. Sen skeema on tarkoituksella puhelias, jotta agentti tietää, mitä tietoja sen pitää ensin hankkia.
{
"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": "fi" },
"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." }
}
}
}Ratkaiseva on kenttä details. Skeeman kuvaus sanoo agentille suoraan, että tarvitaan konkreettisia yksityiskohtia, ei adjektiiveja. Hyvä agentti ei kysy "millainen isäsi on" vaan "mitä hän sanoo aina, kun jokin ärsyttää häntä".
{
"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.tekoalylaulu.fi/preview/sng_3n8Kd2ZpQv.mp3",
"paid": false
},
"isError": false
}Vastaus sisältää tekstin agentille ja rakenteiset tiedot koodille. Kutsu palaa heti, tuotanto jatkuu taustalla.
Jokainen työkalu palauttaa kaksi asiaa: luettavan tekstilohkon, jonka agentti voi antaa suoraan eteenpäin, ja kentän structuredContent, jossa samat tiedot ovat koneelle sopivassa muodossa. Agentti voi siis vastata käyttäjälle menettämättä tunnisteita.
Laulujen tunnisteet ovat samat kuin REST-rajapinnassa. MCP:llä luodun laulun voi myöhemmin hakea RESTin kautta ja toisin päin, mistä on hyötyä kun agentti kerää toimeksiannon ja toimituksesta huolehtii oma taustajärjestelmäsi.
Työkalujen lisäksi palvelin tarjoaa resursseja eli vain luettavaa sisältöä, jonka asiakas voi ladata kontekstiin ilman työkalukutsua.
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 paymentsong://options sisältää kaikki sallitut arvot, song://guide/details lyhyen oppaan siitä, mikä tekee laulusta henkilökohtaisen, song://songs/{id} yksittäisen laulun sanoituksineen ja tiloineen. Opas on ennen kaikkea agenteille: se nostaa selvästi todennäköisyyttä, että ne kysyvät oikeita asioita.
Palvelin tuo mukanaan valmiit kehotteet, jotka asiakas voi tarjota komentoina. Ne säästävät käyttäjältä sen selvittelyn, mitä hänen pitäisi kertoa.
{
"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 vie agentin lyhyen keskustelun läpi, jonka lopussa on käyttökelpoinen toimeksianto. write_song_brief muuttaa olemassa olevan tekstin, esimerkiksi asiakkaan viestin, jäsennellyksi toimeksiannoksi. suggest_occasion auttaa, kun tilaisuus ei sovi tavallisiin luokkiin.
Näin se näyttää käytännössä, käyttäjän kanssa joka ei vielä oikein tiedä mitä haluaa.
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.Ydin on keskellä. Agentti ei tyydy ensimmäiseen yleiseen kuvaukseen vaan kysyy kahdesti tarkentaen, ja juuri nuo kaksi kysymystä muuttavat kenen tahansa laulun tämän ihmisen lauluksi.
Agentti ei voi käynnistää maksua. Se voi vain luoda maksulinkin ja välittää sen, maksaminen tapahtuu selaimessa. Näin se on rakennettu tarkoituksella: mallin ei pidä tehdä ostopäätöstä, jota ihminen ei ole nähnyt.
get_checkout_link antaa osoitteen, joka on voimassa 24 tuntia. Maksun jälkeen laulu siirtyy tilaan complete, ja seuraavalla get_song-kutsulla koko äänite on valmiina. Agentin ei tarvitse tilata mitään, myöhempi kutsu riittää.
Jos hoidat maksun omassa järjestelmässäsi ja laskutat meiltä vain suorituksen, avaamme pyynnöstä suoran tien REST-rajapinnasta. Silloin maksulinkkiä ei tarvita ja laulu vapautuu heti.
Jokainen avain kantaa oikeuksia. Oletus on luku ja kirjoitus ilman laskutusoikeutta, mikä sopii useimmille agenteille.
| Laajuus | Arvo | Sallii |
|---|---|---|
| songs:read | Laulujen haku, listaus ja sanoitusten lukeminen. Ilman tätä oikeutta palvelin ilmoittaa tyhjän työkalulistan. | |
| songs:write | Laulujen luonti ja uudelleenluonti. Aiheuttaa tuotantokustannuksia. | |
| billing | Maksulinkkien luonti ja maksun tilan lukeminen. Tarvitaan vain, jos agentin pitää välittää linkkejä. |
Työkalut, joihin oikeus puuttuu, eivät näy työkalulistalla lainkaan. Se on miellyttävämpää kuin virheilmoitus kesken keskustelun, koska malli ei silloin tarjoa mitään mihin se ei kuitenkaan pysty.
Virheet tulevat työkalun tuloksena, jossa on isError: true ja ymmärrettävä teksti, eivät protokollavirheenä. Näin agentti voi reagoida ja selittää käyttäjälle mitä puuttuu sen sijaan että keskeyttäisi.
{
"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.tekoalylaulu.fi/c/cs_live_8Hd2Kq..." }
],
"isError": true
}Virhekoodit vastaavat REST-rajapinnan koodeja: validation_error, rate_limit, not_found, permission_error, api_error. Teksti on muotoiltu niin, että agentti voi antaa sen sanasta sanaan eteenpäin.
Voimassa ovat samat rajat kuin REST-rajapinnassa: 60 työkalukutsua minuutissa avainta kohti ja kymmenen rinnakkaista tuotantoa. Ylimenevät kutsut jäävät jonoon sen sijaan että kaatuisivat.
MCP-istunto pysyy auki niin kauan kuin asiakas pitää sitä auki. 30 minuutin jouten olon jälkeen suljemme yhteyden; jokainen nykyinen asiakas yhdistää itse takaisin.
Kun määrä kasvaa, kirjoita meille, niin nostamme rajoja.
Sen, minkä agentti meille välittää, käytämme tämän yhden laulun tuottamiseen emmekä mihinkään muuhun. Emme opeta omia malleja käyttäjiesi sisällöillä.
Syötteet ja valmiit laulut säilyvät 90 päivää, sitten ne poistetaan. Aiempaan poistoon on DELETE /v1/songs/{id} REST-rajapinnassa.
Muistuta käyttäjiä siitä, että he kertovat yksityisiä asioita oikeista ihmisistä. Agentin pitää kysyä konkreettisia yksityiskohtia ohjaamatta keskustelua arkaluonteisiin terveys- tai raha-asioihin.
MCP-palvelin pyörii samalla infrastruktuurilla kuin REST-rajapinta. Erillistä asennettavaa tai päivitettävää komponenttia ei ole: uusia työkaluja lisätään vähitellen, olemassa olevat pysyvät vakaina.
Asiakkaan pitää lukea työkalulista käynnistyksessä eikä kirjoittaa sitä kiinteästi koodiin. Se on tavallinen tapa ja tuo sinulle uudet asiat ilman koodimuutoksia.
Suunnitelluista huoltotöistä ilmoitamme aktiivisille tileille sähköpostilla vähintään 48 tuntia etukäteen. Toistaiseksi suunniteltuja katkoja ei ole ollut.
Kysymykset asetuksista, laajuuksista, korkeammista rajoista tai erikoistapauksista: songs@maxkuch.com. Teknisissä ongelmissa mainitse työkalun nimi ja kutsun suunnilleen kellonaika.
Suoraa integraatiota agentin sijaan haluava löytää REST-rajapinnan osoitteesta /api/. Molemmat tiet käyttävät samoja avaimia ja samoja tunnisteita.
Avaimet jaetaan käsin. Lyhyt viesti hankkeestasi, arvioidusta määrästä ja kielistä riittää, ja avaus vie yleensä yhden arkipäivän.