Server MCP

Introduzione

Il Model Context Protocol è lo standard aperto con cui gli assistenti di intelligenza artificiale parlano con sistemi esterni. Il nostro server espone tutta la produzione musicale come strumenti MCP: l’agente può creare una canzone, controllarne lo stato, recuperare testo e audio e avviare una rigenerazione.

Il vantaggio rispetto all’API REST è la conversazione. Un agente sa quali dettagli mancano perché la canzone diventi personale e li chiede da solo. L’utente racconta di suo padre, l’agente ne ricava un briefing e commissiona la canzone.

Il server gira su https://mcp.tuacanzone.it e parla HTTP con Server-Sent Events, il trasporto che tutti i client attuali supportano. Usa le stesse chiavi dell’API REST, quindi chi già integra non ha bisogno di nuove credenziali.

Accesso

Le chiavi vengono rilasciate a mano, come per l’API REST. Scrivi a songs@maxkuch.com indicando che cosa vuoi costruire, il volume atteso e le lingue. Di norma l’attivazione richiede un giorno lavorativo.

Riceverai una chiave di test con il prefisso sk_test_ e una live con il prefisso sk_live_. Con la chiave di test tutti gli strumenti funzionano allo stesso modo, ma non parte alcuna produzione reale e non costa nulla.

Chi ha già una chiave API non ha bisogno di nient’altro: la stessa chiave apre il server MCP.

Connessione

L’indirizzo del server è https://mcp.tuacanzone.it/sse. L’autenticazione avviene con un bearer token nell’header Authorization, esattamente come nell’API REST.

Il server implementa la versione di protocollo 2026-03-26 e annuncia le sue capacità durante l’handshake: strumenti, risorse e prompt. I client che conoscono solo versioni precedenti restano compatibili, semplicemente senza i prompt.

curl https://mcp.tuacanzone.it/health

Installazione nei client

Praticamente tutti i client MCP si configurano con un piccolo file JSON. Di seguito le tre varianti più frequenti, ognuna con la chiave inserita al posto giusto.

Claude Code

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

Claude Desktop

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

Cursor

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

Dopo il riavvio del client gli strumenti compaiono nell’elenco. Se non succede, la causa è quasi sempre una chiave mancante o un JSON con un errore di sintassi.

Strumenti

Il server mette a disposizione sette strumenti. Sono deliberatamente pochi e con nomi chiari, perché un agente scelga bene.

Solo create_song e regenerate_song cambiano qualcosa. I client che chiedono conferma per le operazioni di scrittura la chiederanno esattamente per questi due.

create_song in dettaglio

È lo strumento centrale. Il suo schema è volutamente esplicito, così l’agente sa quali informazioni deve procurarsi prima.

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

Il campo details è quello decisivo. La descrizione dello schema dice chiaramente all’agente che servono dettagli concreti, non aggettivi. Un buon agente non chiede "com’è tuo padre" ma "che cosa dice sempre quando qualcosa lo infastidisce".

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

La risposta contiene testo per l’agente e dati strutturati per il codice. La chiamata ritorna subito, la produzione continua in background.

Forma delle risposte

Ogni strumento restituisce due cose: un blocco di testo leggibile che l’agente può riferire direttamente, e structuredContent con gli stessi dati in forma utilizzabile dalla macchina. Un agente può quindi rispondere all’utente senza perdere gli identificativi.

Gli identificativi delle canzoni sono gli stessi dell’API REST. Una canzone creata via MCP si recupera più tardi via REST e viceversa, il che è utile quando l’agente raccoglie il briefing e il tuo backend gestisce la consegna.

Risorse

Oltre agli strumenti il server offre risorse, cioè contenuti di sola lettura che un client può caricare nel contesto senza chiamare uno strumento.

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 contiene tutti i valori validi, song://guide/details una guida breve su che cosa rende personale una canzone, song://songs/{id} una singola canzone con testo e stato. La guida serve soprattutto agli agenti: rende molto più probabile che chiedano le cose giuste.

Prompt

Il server porta con sé prompt pronti che un client può offrire come comandi. Risparmiano all’utente la spiegazione di che cosa deve raccontare.

{
  "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 guida l’agente in un breve dialogo che porta a un briefing utilizzabile. write_song_brief trasforma un testo esistente, per esempio la mail di un cliente, in un briefing strutturato. suggest_occasion aiuta quando l’occasione non rientra nelle categorie usuali.

Un dialogo tipico

Ecco come appare in pratica, con un utente che non sa ancora bene cosa vuole.

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.

Il punto è la parte centrale. L’agente non prende la prima descrizione generica ma chiede due volte, e sono proprio quelle due domande a trasformare una canzone qualunque in una canzone su questa persona.

Pagamento

Un agente non può avviare un pagamento. Può solo generare un link di pagamento e passarlo, si paga nel browser. È costruito così di proposito: un modello non deve prendere una decisione di acquisto che una persona non ha visto.

get_checkout_link restituisce un URL valido 24 ore. Dopo il pagamento la canzone passa allo stato complete e alla chiamata successiva di get_song la registrazione completa è pronta. L’agente non deve sottoscrivere nulla, basta una chiamata successiva.

Chi gestisce il pagamento nel proprio sistema e ci fattura soltanto può farsi abilitare su richiesta la via diretta dell’API REST. In quel caso il link di pagamento non serve e la canzone viene sbloccata subito.

Diritti e scope

Ogni chiave porta con sé dei permessi. Lo standard è lettura e scrittura senza accesso alla fatturazione, il che va bene per la maggior parte degli agenti.

Gli strumenti per cui manca il permesso non compaiono affatto nella lista degli strumenti. È più piacevole di un messaggio di errore in mezzo al dialogo, perché il modello non propone nulla che comunque non potrebbe fare.

Errori

Gli errori arrivano come risultato di strumento con isError: true e un testo comprensibile, non come errore di protocollo. Così l’agente può reagire e spiegare all’utente cosa manca, invece di interrompersi.

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

I codici di errore corrispondono a quelli dell’API REST: validation_error, rate_limit, not_found, permission_error, api_error. Il testo è formulato in modo che un agente possa riferirlo parola per parola.

Limiti

Valgono gli stessi limiti dell’API REST: 60 chiamate di strumento al minuto per chiave e dieci produzioni contemporanee. Le chiamate successive restano in coda invece di fallire.

Una sessione MCP resta aperta finché il client la mantiene. Dopo 30 minuti di inattività chiudiamo la connessione; ogni client attuale si riconnette da solo.

Se il volume cresce, scrivici e alziamo i limiti.

Dati

Ciò che l’agente ci trasmette lo usiamo per produrre quella canzone e per nient’altro. Nessun addestramento di modelli nostri sui contenuti dei tuoi utenti.

I dati inseriti e le canzoni finite restano 90 giorni, poi vengono cancellati. Per cancellare prima usa DELETE /v1/songs/{id} dell’API REST.

Ricorda agli utenti che raccontano cose private su persone reali. Un agente dovrebbe chiedere dettagli concreti senza spingere verso informazioni sensibili di salute o finanziarie.

Esercizio

Il server MCP gira sulla stessa infrastruttura dell’API REST. Non c’è un componente separato da installare o aggiornare: aggiungiamo nuovi strumenti in modo additivo, quelli esistenti restano stabili.

Un client dovrebbe leggere l’elenco degli strumenti all’avvio invece di scriverlo nel codice. È il modo standard e ti consegna le novità senza modifiche.

Per le manutenzioni programmate avvisiamo per mail gli account attivi con almeno 48 ore di anticipo. Non ci sono state finestre di fermo pianificate.

Assistenza

Domande sull’installazione, scope, limiti più alti o casi particolari: songs@maxkuch.com. Per i problemi tecnici indica il nome dello strumento e l’ora approssimativa della chiamata.

Chi vuole integrare direttamente invece di passare da un agente trova l’API REST su /api/. Entrambe le strade usano le stesse chiavi e gli stessi identificativi.