Server MCP per la trascrizione del tuo account

Il server MCP per la trascrizione di Hushscript collega un assistente alle tue registrazioni e trascrizioni tramite il Model Context Protocol. Approva una connessione OAuth nel browser oppure fornisci un token di accesso personale. La trascrizione e le azioni a pagamento seguono le regole di finanziamento del tuo account personale o dello spazio di lavoro idoneo.

Due server

Hushscript gestisce due server MCP separati, e la maggior parte dei lettori ne ha bisogno solo di uno.

https://mcp.hushscript.com/mcp è il server dell’account descritto nel resto di questa pagina. Accetta OAuth o un token di accesso personale, e permette di lavorare sull’account: caricare, trascrivere, modificare, esportare.

POST https://hushscript.com/mcp è un server di documentazione gratuito e separato. Nessun account, nessun token, niente a cui accedere. È di sola lettura e anonimo: non può aprire un account, avviare una trascrizione, né toccare nulla che appartenga a un account. Risponde a domande su prezzi, funzionalità, contenuto delle pagine e come connettersi, tramite cinque strumenti (get_pricing, get_capabilities, how_to_connect, list_pages, get_page) e le stesse informazioni come tre risorse (hushscript://pricing, hushscript://capabilities, hushscript://connect).

Se sei un agente che ha appena scoperto Hushscript, non possiedi alcun token, e stai ancora decidendo se fa al caso tuo prima di spendere qualcosa, inizia dal server di documentazione. Torna al resto di questa pagina quando sei pronto a connettere un account.

Connessione

Il server parla Streamable HTTP su un unico endpoint:

https://mcp.hushscript.com/mcp

Non esiste un endpoint SSE e non c’è software Hushscript da installare localmente. In Claude Code:

claude mcp add --transport http hushscript https://mcp.hushscript.com/mcp

In un client che accetta una configurazione JSON:

{
  "mcpServers": {
    "hushscript": {
      "type": "http",
      "url": "https://mcp.hushscript.com/mcp"
    }
  }
}

Un client compatibile con OAuth legge /.well-known/oauth-authorization-server per scoprire gli endpoint. Può registrarsi tramite /oauth/register oppure usare un documento di metadati con l’ID del client, poi apre una finestra del browser per l’accesso.

Cosa approvi

L’autorizzazione avviene tramite OAuth 2.1 con PKCE. La finestra del browser è una schermata di consenso di Hushscript, non una casella per la password del client: indica il nome dell’applicazione che lo richiede, elenca in linguaggio semplice cosa vuole fare, e aspetta la tua conferma. Niente viene concesso finché non lo approvi lì.

I token di accesso durano un’ora e i token di rinnovo durano trenta giorni. Con OAuth, il client gestisce queste credenziali per te: non devi incollare un token di accesso personale nella configurazione.

Senza browser

Una connessione OAuth richiede l’approvazione nel browser. Lo stesso server accetta anche direttamente un token di accesso personale, senza passaggi nel browser al momento della connessione. Una persona ne crea uno sotto Token nella pagina MCP dell’account, sceglie gli scope e decide se può acquistare minuti. Il token viene mostrato una sola volta, ha la forma hsr1:<region>:pat.<id>.<secret> e va inserito in Authorization: Bearer <token> su ogni richiesta: nessuno scambio OAuth, nessuna schermata di consenso, nessuna registrazione del client. Lo stesso token funziona anche con la REST API.

Un token può anche appartenere a un account macchina senza un titolare umano. Un agente avvia una registrazione a pagamento con POST /v1/agent/accounts, completa Stripe Checkout ospitato in un browser che può controllare e attiva l’account con un segreto monouso tramite POST /v1/agent/accounts/{signup_id}/claim per ottenere il primo token. Quel token si connette qui come qualsiasi altro. Vedi Uso automatizzato per il flusso completo.

Un token non può creare, elencare o revocare altri token. Un account può avere al massimo 25 token attivi. Il primo token dell’account macchina può ruotare se stesso tramite la REST API; il flusso è descritto in Uso automatizzato.

Permessi

Una connessione dispone di un insieme di scope. Una richiesta OAuth che non ne specifica alcuno riceve per impostazione predefinita dieci degli undici scope selezionabili, tutti tranne billing. Una persona sceglie gli scope quando crea un token nell’app. Il primo token di un account macchina ha solo transcripts:read, transcripts:write, transcribe, account:read, export, billing e lo scope separato pat:rotate per ruotare se stesso. L’attivazione dell’account abilita entrambe le impostazioni di fatturazione; per un token creato da una persona occorre abilitarle esplicitamente. Quando gli scope sono noti, il server pubblica gli strumenti corrispondenti; il backend verifica gli scope a ogni chiamata.

billing è sempre un’eccezione. Non viene mai concesso implicitamente e la schermata di consenso ti avvisa prima dell’approvazione. Uno strumento di acquisto richiede che siano abilitate sia l’impostazione di fatturazione del token sia quella dell’account. pat:rotate non può essere selezionato in una richiesta OAuth né nel modulo di creazione dei token nell’app.

Cosa coprono gli strumenti

56 strumenti, raggruppati per ambito:

export_transcript restituisce TXT, SRT, VTT, Markdown o JSON. Il set completo di 21 formati di esportazione si trova nell’app.

Oltre agli strumenti, il server pubblica tre risorse e una stringa instructions alla connessione: i pacchetti di minuti, il modello di credito e di scope, e il catalogo completo dei codici di errore, così un client può leggere le regole prima di chiamare qualsiasi cosa. Ogni strumento di elenco con paginazione accetta un limit e un cursor opaco restituito dalla pagina precedente come next_cursor; list_packs e list_payment_methods restituiscono i rispettivi elenchi senza cursore.

I caricamenti MCP inviano audio già preparato. Per un video locale, prepara prima l’audio sul tuo dispositivo; transcribe_from_url recupera sul server link audio supportati e non importa link video. I job avviati tramite MCP usano la modalità standard: le trascrizioni vengono salvate secondo le impostazioni di conservazione dell’account. La modalità privata per singola trascrizione è disponibile nell’app, non tramite i token MCP.

Esempi

Un client che segue il flusso OAuth ottiene una normale sessione MCP e non vede mai direttamente nulla di tutto questo: il suo SDK costruisce il JSON-RPC internamente. È lo stesso protocollo che un client dotato di token invia a mano, e funziona come strumento di debug in entrambi i casi.

Connettiti con un token mettendolo direttamente nella richiesta, senza altro handshake oltre a initialize:

curl -s https://mcp.hushscript.com/mcp \
  -H "Authorization: Bearer hsr1:us:pat.4f2a1c.9e7b3d2a5c8f1e6b4a0d7c3f2e1b9a8d" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "example-client", "version": "1.0.0" }
    }
  }'

Invia di nuovo la stessa richiesta con un corpo diverso per vedere tutti gli strumenti che gli scope del token coprono:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Ogni voce porta un nome, una descrizione e uno schema JSON inputSchema, corrispondenti ai gruppi indicati sopra. Questa chiamata a create_upload riserva credito e avvia un caricamento:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_upload",
    "arguments": {
      "size_bytes": 52428800,
      "duration_seconds": 1800,
      "title": "Team standup 2026-09-10",
      "transcription_options": { "speaker_detection": true }
    }
  }
}

Gli strumenti con risposte strutturate, come create_upload, restituiscono un blocco di testo content con JSON serializzato come stringa. Per esempio:

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"job_id\": \"job_8f3a1c2b9e\",\n  \"balance_seconds\": 5400,\n  \"held_seconds\": 1800,\n  \"upload\": {\n    \"part_size_bytes\": 33554432,\n    \"total_parts\": 2,\n    \"part_urls\": [\n      { \"n\": 1, \"url\": \"https://...\" }\n    ],\n    \"next_part_number\": 2\n  }\n}"
    }
  ]
}

La risposta sopra mostra i campi del caricamento; quella completa include anche limits, funding e state. Carica i byte su quegli URL, chiama complete_upload con l’ETag di ogni parte, poi interroga get_job finché lo stato non è done. Gli esempi strutturati qui sotto mostrano direttamente il JSON interno, già analizzato, e omettono il wrapper della richiesta {"jsonrpc":"2.0","id":...} perché non cambia: cambiano solo name e arguments.

export_transcript restituisce il formato renderizzato come testo e download_account_export_chunk restituisce i byte grezzi codificati come testo base64. Analizza il text di un risultato come JSON solo se lo strumento restituisce dati strutturati.

Elencare e leggere le trascrizioni:

{
  "name": "list_transcripts",
  "arguments": { "limit": 5 }
}

{
  "transcripts": [
    {
      "id": "t_9c2b7f10",
      "title": "Team standup 2026-09-10",
      "language_detected": "en",
      "duration_seconds": 1800,
      "tags": ["standup"],
      "insights_state": "none"
    }
  ],
  "next_cursor": null
}

Generare Insights, gratuiti alla prima chiamata per una trascrizione. Questo esempio mostra il saldo dopo l’avvio di una nuova generazione; reused è false:

{
  "name": "generate_insights",
  "arguments": { "id": "t_9c2b7f10" }
}

{
  "ok": true,
  "reused": false,
  "balance_seconds": 5400,
  "held_seconds": 0
}

Acquistare minuti: idempotency_key è obbligatorio in modo che un nuovo tentativo dopo una risposta persa non possa addebitare due volte:

{
  "name": "purchase_pack",
  "arguments": {
    "pack": "300min",
    "payment_method_id": "pm_1PxYzABC",
    "idempotency_key": "agent-2026-09-11-refill-01"
  }
}

{
  "status": "ok",
  "balance_seconds": 23400
}

Le risorse rispondono senza una chiamata a uno strumento: resources/read indica uno dei tre URI:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "resources/read",
  "params": { "uri": "hushscript://pricing" }
}

Risposta abbreviata (la nota esplicativa della risorsa è omessa):

{
  "contents": [
    {
      "uri": "hushscript://pricing",
      "mimeType": "application/json",
      "text": "{\"packs\":[{\"id\":\"45min\",\"minutes\":45},{\"id\":\"300min\",\"minutes\":300},{\"id\":\"900min\",\"minutes\":900},{\"id\":\"1800min\",\"minutes\":1800},{\"id\":\"6000min\",\"minutes\":6000}]}"
    }
  ]
}

Usa list_packs per gli importi e le valute attuali dei pacchetti.

Ogni errore del backend porta uno slug stabile e un codice numerico, lo stesso corpo {"error": "<slug>", "code": <number>} documentato in hushscript://error-codes. Una chiamata a uno strumento espone quello stesso slug e codice, incorporato in un messaggio leggibile invece che in un oggetto di errore grezzo, e segnala il risultato con isError invece di sollevare un’eccezione:

{
  "content": [
    {
      "type": "text",
      "text": "Not enough transcription credit. This job needs 1800 seconds and the balance is 900 seconds. Top up at https://app.hushscript.com/billing (insufficient_balance, E3001)"
    }
  ],
  "isError": true
}

Quali azioni consumano minuti

Leggere i dati dell’account non consuma minuti di trascrizione. Le azioni a pagamento usano le stesse tariffe dell’app. Di solito vengono finanziate dai minuti personali prepagati; una trascrizione dello spazio di lavoro può usare un pool Teams quando il pool attivo copre da solo l’intero job e non è selezionata alcuna lingua di traduzione. Un job con lingue di traduzione o con un URL audio importato usa minuti personali. Il finanziamento non cambia la custodia della trascrizione.

Gli account personali idonei ricevono 30 minuti gratuiti dopo la verifica della carta; un account macchina parte con il pacchetto acquistato durante la registrazione.

• Trascrivere una registrazione consuma minuti pari alla sua durata. La modalità medica aggiunge il 100% e ogni lingua di traduzione il 25%. Con il multicanale attivo, ogni canale audio viene fatturato separatamente, quindi un file stereo conta il doppio.
• Insights: la prima generazione per trascrizione è gratuita. Rigenerarli in seguito costa il 40% della durata della registrazione a partire dall’Originale, oppure il 30% a partire dalla versione Pulita. La rigenerazione usa i minuti personali del membro, anche quando un pool dello spazio di lavoro ha pagato la trascrizione.
• Ritradurre una trascrizione costa il 25% della sua durata per lingua e sovrascrive: per ogni lingua addebitata dalla chiamata, qualsiasi copia modificata a mano di quella traduzione viene persa senza possibilità di recupero.
• purchase_pack addebita subito una carta salvata idonea se l’acquisto riesce. Richiede lo scope billing e le impostazioni di fatturazione abilitate sia sul token sia sull’account. Aggiunge minuti al saldo personale, non a un pool Teams.
• add_payment_method non costa nulla. Restituisce un link di Stripe Checkout che salva una carta sull’account senza addebitarla; completalo una volta nel browser (un agente può controllare il proprio). In seguito, purchase_pack tenta un addebito fuori sessione; un rifiuto o una richiesta di autenticazione dell’emittente restituisce un codice di errore distinto invece di una pagina incompleta.

Vedi i prezzi per i pacchetti.

Verifica e revoca

Per un account a cui puoi accedere, le connessioni OAuth compaiono sotto App connesse nella pagina MCP del tuo account, con il client e gli scope. Anche i token sono elencati lì; revocarne uno interrompe le sue chiamate. Rimuovere una configurazione del client impedisce solo a quel client di inviare richieste. Un account macchina non ha una casella email utilizzabile per l’accesso, quindi il suo token ruota se stesso tramite il flusso dell’account agente.

Limiti

I token degli account umani consentono 1.200 richieste al minuto ciascuno. I token successivi di un account agente condividono questo limite anche dopo le rotazioni. Le rotte di fatturazione che chiamano Stripe tramite token condividono un limite di 60 richieste al minuto per account: salvataggio della carta, acquisto, cambio della carta predefinita, rimozione della carta e richieste dell’elenco carte non presenti nella cache. Gli acquisti degli account agente e quelli tramite token degli account umani hanno un limite di tre tentativi per ogni intervallo mobile di 24 ore per account. L’acquisto iniziale dell’agente conta, così come gli errori dopo che un tentativo è stato riservato; gli acquisti tramite sessione browser umana sono esclusi. Il superamento del limite restituisce HTTP 429 / codice 4038 agent_purchase_capped, distinto dalla normale limitazione HTTP 429 / codice 5000 rate_limited. Entrambi forniscono Retry-After.

L’autorizzazione OAuth e il suo completamento condividono un limite di 30 richieste al minuto per indirizzo. La registrazione ha un limite separato di 30 al minuto; /oauth/token ne ha uno separato di 600 al minuto. Ciascuno usa come chiave un indirizzo IPv4 o una rete IPv6 /64. Le verifiche dei token grezzi non presenti nella cache hanno un altro limite di 30 al minuto con la stessa chiave; non è un limite su ogni chiamata a uno strumento MCP.