Server MCP

@spicyapi/mcp permette all’assistente IA che usi già (Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI e altri) di lavorare con SpicyAPI al posto tuo. Una volta configurato puoi scrivere «fammi un video di cinque secondi da questa foto» e l’assistente trova un modello adatto, ti dice il prezzo, aspetta il tuo OK, avvia il lavoro e ti consegna il link al risultato.

Non devi scrivere codice. Ti servono Node.js, una chiave API e una decina di minuti.

Che cos’è MCP, in parole semplici

MCP (Model Context Protocol) è uno standard aperto per dare capacità in più agli assistenti IA. Immaginalo come una presa a cui collegare delle estensioni: un assistente che supporta MCP può caricare dei «server», e ogni server aggiunge un insieme di strumenti (tool) che l’assistente può usare mentre parla con te.

@spicyapi/mcp è uno di questi server. Aggiunge 15 strumenti SpicyAPI. Ecco che cosa succede quando chiedi qualcosa:

1. Scrivi un normale messaggio, per esempio «Genera l’immagine di un faro all’alba.»
2. L’assistente decide quali strumenti SpicyAPI gli servono e li chiama.
3. Il server, un piccolo programma che gira sul tuo computer e che l’app dell’assistente avvia da sola, invia quelle richieste a SpicyAPI usando la tua chiave API.
4. Tutto ciò che costa denaro prima si ferma: l’app ti mostra il prezzo e ti chiede di confermare. L’assistente non può rispondere a quella domanda al posto tuo.
5. I risultati tornano nella conversazione e l’assistente te li spiega.

Non c’è niente da ospitare né da tenere acceso. L’app dell’assistente avvia il server quando le serve e lo ferma quando la chiudi.

Fa al caso tuo se usi già un assistente IA e vuoi provare modelli, confrontare prezzi o produrre immagini e video senza scrivere un programma. Anche gli sviluppatori lo usano per esplorare il catalogo dall’interno del proprio editor prima di costruire un’integrazione.

Non è lo strumento giusto per un’app o un backend in produzione (usa l’SDK o l’API HTTP), per grandi lotti eseguiti senza supervisione (usa la CLI) né per ricevere le risposte di una chat in streaming, token dopo token: il server MCP invia e segue attività; per la chat vedi Testo e streaming.

MCP, CLI, SDK o Skill?

SpicyAPI pubblica quattro pacchetti distinti. Alla maggior parte delle persone ne bastano uno o due.

Se la tua app non è scritta in TypeScript, la riga dell’SDK ha altre quattro opzioni: Python, Go, PHP e Java.

Che cosa può fare il tuo assistente

Questi sono tutti i 15 strumenti che il server aggiunge. Non li chiami mai per nome: chiedi con parole tue e l’assistente sceglie. I nomi ti servono quando leggi che cosa ha fatto l’assistente, o quando l’app ti chiede di approvare la chiamata a uno strumento.

«Ti chiede prima» significa che è il server SpicyAPI stesso a fermarsi e a chiedere conferma: l’assistente non può saltare questo passaggio. Molte app chiedono anche il tuo permesso prima di eseguire qualsiasi strumento; quella è un’impostazione dell’app e non ha niente a che vedere con questa.

Prima di iniziare

node --version

Configura il tuo client

Tutte le app qui sotto eseguono lo stesso comando: npx --yes --package=@spicyapi/mcp spicyapi-mcp. Al primo avvio scarica il pacchetto, e può volerci qualche secondo.

Non devi mai eseguire quel comando tu stesso: lo avvia l’app. Se lo esegui a mano, resta in silenzio in attesa che l’app gli parli; sembra bloccato, ma è normale. Premi Ctrl+C per fermarlo.

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" }
    }
  }
}

Ogni app decide dove si trova la sua configurazione e in che formato, ed entrambe le cose cambiano da una versione all’altra. Quando un passaggio qui sopra non corrisponde più alla tua app, fa fede la documentazione MCP dell’app stessa. Qualsiasi altra app compatibile con MCP può usare gli stessi command, args ed env mostrati sopra.

Tieni al sicuro la tua chiave

Chiunque abbia la tua chiave può spendere il tuo saldo. Poche abitudini bastano a contenere il rischio:

• Metti la chiave solo in file a livello utente, cioè quelli nella tua cartella home elencati sopra, mai in un file dentro un progetto o un repository. Se fai il backup dei tuoi file di impostazioni in un repository «dotfiles» pubblico, lasciali fuori.
• Non incollare mai la chiave nella chat. All’assistente non serve: il server la legge dalla configurazione.
• Imposta un limite giornaliero sulla chiave, così un errore ha un tetto.
• Se una chiave trapela, revocala nella pagina Chiavi API e creane una nuova. La revoca ha effetto immediato; le attività già accettate arrivano comunque alla fine e vengono comunque addebitate. Vedi Autenticazione.

Verifica che funzioni

In una nuova conversazione chiedi queste tre cose, nell’ordine:

1. «Controlla lo stato del servizio SpicyAPI.» Usa spicyapi_service_status. Non richiede la chiave, quindi se funziona il server è installato correttamente.
2. «Qual è il mio saldo SpicyAPI?» Usa spicyapi_balance_get. Se funziona, la tua chiave arriva al server.
3. «Quali strumenti SpicyAPI hai?» L’assistente dovrebbe elencare 15 strumenti il cui nome inizia con spicyapi_.

Nessuna di queste richieste costa nulla. Se una fallisce, vedi Risoluzione dei problemi.

Provalo: conversazioni di esempio

Copia una qualsiasi di queste richieste nel tuo assistente. Le descrizioni indicano quali strumenti userà di solito (gli assistenti si comportano in modo diverso, quindi l’ordine esatto può cambiare) e in quale punto preciso si ferma a chiederti conferma.

Controllare saldo e spese

Quanto saldo SpicyAPI ho, e quanto ho speso questa settimana?

L’assistente chiama spicyapi_balance_get e spicyapi_usage_get. Sono entrambi gratuiti e di sola lettura, quindi non viene chiesta alcuna conferma. «Held» nel saldo indica il denaro accantonato dalle attività ancora in corso.

Trovare e confrontare modelli

Trova i modelli SpicyAPI che trasformano un’immagine fissa in un video, e confronta quanto costerebbe con ciascuno una clip di 5 secondi.

L’assistente chiama spicyapi_models_list (filtrando i modelli video che accettano un’immagine), può chiamare spicyapi_model_get per i dettagli e può chiamare spicyapi_task_quote una volta per ogni candidato, per avere il prezzo esatto con le tue impostazioni. I preventivi sono gratuiti e non creano nulla, quindi non c’è alcuna conferma. La risposta è un confronto tra cui puoi scegliere.

Generare un’immagine

Usa SpicyAPI per generare un’immagine quadrata di un ristorante di ramen illuminato al neon in una notte di pioggia. Scegli un modello di immagini economico e dammi il link quando ha finito.

1. spicyapi_models_list per scegliere un modello, e spicyapi_model_get se gli servono i campi accettati da quel modello.
2. spicyapi_task_create. È qui che si ferma. L’app mostra una conferma con il modello, l’addebito stimato, l’addebito massimo e la scadenza del preventivo. Non viene addebitato nulla finché non confermi.
3. Dopo la tua conferma, l’attività parte e spicyapi_task_wait attende che finisca.
4. L’assistente ti dà il link al risultato preso dall’attività conclusa.

Trasformare una foto del tuo computer in un video

Trasforma la foto in /Users/me/Desktop/portrait.jpg in un video di 5 secondi in cui la telecamera si avvicina lentamente.

Su Windows, indica il percorso come C:\Users\me\Desktop\portrait.jpg.

1. spicyapi_upload_file carica la foto e restituisce un indirizzo spicy:// che la rappresenta. Il caricamento è gratuito e non chiede conferma, ma invia davvero quel file a SpicyAPI: indica quindi il percorso esatto del file che intendi.
2. spicyapi_models_list / spicyapi_model_get per scegliere un modello da immagine a video e vederne le opzioni.
3. spicyapi_task_create: qui si ferma per la tua conferma, mostrando il prezzo.
4. spicyapi_task_wait. I video richiedono spesso diversi minuti; ogni attesa dura al massimo cinque minuti, quindi l’assistente può attendere più di una volta, oppure puoi chiedere dell’attività più tardi.

Ritrovare un’attività precedente

Mostrami le mie attività SpicyAPI degli ultimi tre giorni che sono fallite, e dimmi perché.

L’assistente chiama spicyapi_tasks_list con un filtro sullo stato fallito, poi spicyapi_task_get sulle attività che ti interessano per leggere l’errore. Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale. Se poi dici «riprova quella», chiama spicyapi_task_retry, che si ferma per la tua conferma, perché un nuovo tentativo è una nuova attività a pagamento.

Ottenere il file del risultato

Dammi il link di download del mio ultimo video SpicyAPI.

L’assistente trova l’attività con spicyapi_tasks_list, poi la legge con spicyapi_task_get, che include link ai risultati pronti all’uso. Apri il link in un browser per scaricare il file. I link durano poco: se uno è scaduto, chiedi di nuovo e l’assistente ne recupera uno nuovo.

Il server MCP non salva da solo i file sul tuo computer. Gli assistenti che possono anche eseguire comandi, per esempio Claude Code o Codex, possono scaricare il link in una cartella per te, se glielo chiedi.

Riferimento degli strumenti

Ogni strumento, che cosa riceve e che cosa restituisce. Gli importi sono sempre dollari statunitensi scritti come testo decimale esatto, senza il simbolo $, per esempio "0.08". Le date sono in UTC.

Controllare il servizio e la documentazione

spicyapi_service_status

Controlla se l’API pubblica di SpicyAPI è raggiungibile e funzionante. Non richiede alcuna chiave API, non costa nulla e non chiede nulla. È uno strumento di diagnosi: l’assistente non ha bisogno di eseguirlo prima di creare un’attività.

Parametri: nessuno.

Restituisce: operational (true o false), i singoli controlli health e readiness con il loro stato HTTP, e checkedAt.

spicyapi_docs_search

Cerca in un indice delle pagine della documentazione di SpicyAPI incluso nel server e restituisce i titoli, i riepiloghi e i link corrispondenti. Non richiede alcuna chiave e non fa alcuna richiesta di rete.

Restituisce: un elenco di voci, ciascuna con slug, title, summary, keywords e url. I link puntano a questo sito di documentazione, nella forma https://docs.spicyapi.ai/docs/retention. Quando non trova nulla, l’elenco è vuoto.

Sfogliare i modelli

spicyapi_models_list

Elenca i modelli che la tua chiave API può chiamare, con prezzi che includono già gli eventuali sconti del tuo account. Gratuito e di sola lettura.

Restituisce: total e items. Ogni voce include model (l’ID esatto da usare), displayName, provider, modality, tasks, enabled e available, availability, un elenco pricing (ogni voce ha un’etichetta di livello, una unit tra per_image, per_second, per_request o per_1k_tokens e un price in USD), startingPrice, taskTimeoutSeconds e, se richiesti, inputSchema / examples.

Alcune impostazioni, come la risoluzione o la durata, cambiano il prezzo. L’elenco dei prezzi serve per confrontare; l’addebito esatto per una richiesta specifica viene da un preventivo.

spicyapi_model_get

Restituisce un modello per intero: gli input accettati (inputSchema, una descrizione leggibile dalle macchine di ogni campo, del suo tipo, dei valori ammessi e dei valori predefiniti), i prezzi, la disponibilità e gli esempi. Gratuito e di sola lettura.

Restituisce: gli stessi campi di una voce di spicyapi_models_list, sempre con inputSchema.

Il tuo account

spicyapi_balance_get

Mostra il tuo saldo. Gratuito e di sola lettura. Non serve prima di creare un’attività: la creazione controlla da sé i fondi.

Parametri: nessuno.

Restituisce: available, held (accantonato dalle attività ancora in corso) e total, in USD. Può includere anche un dettaglio funding con fondi prepagati, bonus promozionali ed eventuale linea di credito approvata; vedi Fatturazione.

spicyapi_usage_get

Riporta che cosa ha fatto questa chiave API: quante attività, quante sono riuscite o fallite, e la spesa liquidata, raggruppate per giorno e per modello. Gratuito e di sola lettura. Riguarda solo la chiave nella tua configurazione, non l’intero account, e non è il tuo saldo.

Restituisce: from, to, currency, totalCalls, totalSpend e gli elenchi days e models con calls, succeeded, failed e spend. Vengono contati solo gli addebiti liquidati; il denaro ancora accantonato dalle attività in corso no, e una liquidazione arrivata in ritardo può aggiornare un giorno precedente.

Attività

spicyapi_tasks_list

Elenca le attività create con questa chiave API, dalla più recente: utile per ritrovare un’attività dopo aver chiuso la chat. Mostra solo i metadati: niente prompt, input o link ai risultati. Gratuito e di sola lettura.

Restituisce: items (ciascuna voce con taskId, model, state, cost, settled, createdAt, deadlineAt e, a fine attività, completedAt), hasMore e nextCursor. cost è definitivo solo quando settled vale true.

spicyapi_task_get

Apre un’attività creata con questa chiave API. Gratuito e di sola lettura.

Restituisce: taskId, model, state, cost, settled, createdAt, completedAt e, a seconda dell’attività:

• output.assets: i risultati. Ogni asset pronto ha un url che puoi aprire direttamente, con il suo expiresAt, il tipo mime e le dimensioni o la durata. Un asset segnato come pending è ancora in fase di archiviazione: chiedi di nuovo tra qualche secondo. Uno segnato come unavailable non c’è più, per sempre.
• errorCode ed errorMessage quando l’attività è fallita; i codici sono elencati in Errori.
• input: ciò che è stato inviato, finché non finisce il periodo di conservazione del prompt.
• contentState (present, expired o purged) e retention, che indica quando verranno rimossi output e prompt.
• sourceTaskId quando questa attività è un nuovo tentativo.

Un ID attività che non esiste e uno che appartiene a qualcun altro restituiscono entrambi «not found».

spicyapi_task_wait

Controlla ripetutamente un’attività finché non finisce o finché l’attesa non si esaurisce, poi la restituisce. Gratuito e di sola lettura. Esaurire il tempo di attesa non annulla l’attività e non la fa fallire: continua a girare, e puoi attendere di nuovo o consultarla più tardi.

Restituisce: l’attività conclusa, nello stesso formato di spicyapi_task_get. Se il tempo finisce prima, lo strumento segnala che l’attività non si è conclusa entro quel tempo.

File

spicyapi_upload_file

Legge un file dal tuo computer, lo carica su SpicyAPI, completa il caricamento e restituisce un indirizzo spicy:// da inserire nell’input di un modello: tutto in una sola chiamata, senza un secondo passaggio. Gratuito, e non chiede conferma; però invia il file, quindi non è di sola lettura.

I file già online a un indirizzo pubblico https:// non hanno bisogno di caricamento: l’assistente può passare quell’indirizzo direttamente al modello, se il modello accetta un URL.

File accettati: immagini JPEG, PNG, WebP e GIF fino a 10 MiB; video MP4 e WebM e audio MP3 e WAV fino a 90 MiB e 600 secondi. Un modello può fissare limiti propri più restrittivi.

Quali cartelle: per impostazione predefinita si possono leggere solo i file dentro la tua cartella home. Vedi File locali.

Restituisce: uri (l’indirizzo spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds quando sono noti, ed expiresAt. Per impostazione predefinita l’indirizzo si può usare per un giorno.

Quando lo strumento ritorna, il caricamento è già completato, quindi non c’è un passaggio di «commit» separato da eseguire. Il server non ha uno strumento per completare un caricamento avviato da un altro programma; il codice che carica in passaggi separati lo completa con commitUploadedFile dell’SDK.

spicyapi_download_url_create

Emette un nuovo link di download firmato per un risultato di una delle tue attività. Gratuito. Di solito non serve: spicyapi_task_get e spicyapi_task_wait includono già link pronti, e richiedere di nuovo l’attività li rinnova.

Restituisce: key, url ed expiresAt. Il link funziona per 20 minuti e, una volta emesso, non può essere revocato: non condividerlo e non salvarlo. Vedi Media.

Preventivi, creazione ed eliminazione

spicyapi_task_quote

Calcola il prezzo esatto di una richiesta specifica senza avviare nulla e senza accantonare denaro. Gratuito e di sola lettura. L’assistente lo usa per confrontare le opzioni; non gli serve prima di creare un’attività, perché la creazione chiede un proprio preventivo.

Restituisce: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit ed expiresAt. Un preventivo vale cinque minuti e solo per quella richiesta esatta.

spicyapi_task_create

Avvia una generazione. Costa denaro e chiede sempre prima a te.

Che cosa succede, nell’ordine:

1. Il server chiede un preventivo esatto per la richiesta. Un preventivo è gratuito: non crea nulla e non accantona denaro.
2. L’app ti mostra una conferma con il modello, l’addebito stimato, l’addebito massimo, la scadenza del preventivo e una chiave di idempotenza (un riferimento che impedisce che la stessa richiesta venga addebitata due volte).
3. Se rifiuti, non viene creata alcuna attività e non viene accantonato né addebitato denaro. L’unica richiesta inviata fino a quel momento è il preventivo gratuito del passaggio 1.
4. Se confermi, SpicyAPI controlla gli input, il prezzo, i permessi della tua chiave e i tuoi fondi, accantona l’importo stimato e avvia l’attività.

Serve un’app in grado di mostrare domande di conferma (elicitation di MCP). In un’app che non ne è capace, lo strumento fallisce al passaggio 2: è stato richiesto il preventivo gratuito, e non è successo nient’altro. Vedi Prima di iniziare.

Restituisce: taskId, state (normalmente queued), estimatedCost e la idempotencyKey usata. L’attività poi prosegue da sola; usa spicyapi_task_wait o spicyapi_task_get per ritirare il risultato.

Se la connessione cade dopo la tua conferma, l’errore include la chiave di idempotenza. Chiedi all’assistente di riprovare con quella stessa chiave e con modello e impostazioni invariati invece di ricominciare da zero: potrebbe esserti chiesto di confermare di nuovo, ma SpicyAPI restituisce l’attività originale invece di addebitarne una seconda. Una chiave nuova creerebbe una seconda attività a pagamento, e impostazioni cambiate con la stessa chiave vengono rifiutate.

spicyapi_task_retry

Crea una nuova attività, addebitata a parte, a partire da una che è failed o expired. L’attività originale resta com’era. Costa denaro e chiede sempre prima a te.

Restituisce: il nuovo taskId, sourceTaskId (l’originale), state, estimatedCost e idempotencyKey.

Il nuovo tentativo usa il prezzo attuale del modello, e i controlli attuali su input, permessi e fondi vengono ripetuti. La sua conferma non mostra un prezzo, quindi se vuoi conoscerlo prima, chiedi all’assistente di fare un preventivo con spicyapi_task_quote per lo stesso modello e le stesse impostazioni prima di riprovare.

Un nuovo tentativo riutilizza l’input originale senza modifiche, quindi leggi prima l’errorCode dell’attività fallita:

• rate_limited, upstream_unavailable, timeout o upstream_failed: vale la pena riprovare una volta, dopo una breve attesa.
• generation_failed: cambia il prompt o l’immagine e avvia invece una nuova attività; lo stesso input di solito fallisce nello stesso modo.
• invalid_asset: carica di nuovo il file e avvia una nuova attività con il nuovo indirizzo spicy://; un nuovo tentativo riutilizzerebbe il vecchio file.
• content_rejected, invalid_request o unsupported_combination: non riprovare senza modifiche. Cambia il prompt, le impostazioni o il modello e avvia una nuova attività.

L’elenco completo è in Errori.

spicyapi_task_purge

Elimina per sempre i contenuti archiviati di un’attività conclusa: i media generati, il payload del risultato (i dati del risultato archiviati), il prompt e l’altro testo dell’input. Non si può annullare e chiede sempre prima a te. Non costa nulla, e non rimborsa nulla.

• Si possono distruggere i contenuti solo delle attività concluse (succeeded, failed, expired o uno storico canceled). Un’attività accettata non si può annullare e non esiste un’API di annullamento, quindi per un’attività queued o running attendi che finisca (spicyapi_task_wait), poi distruggine i contenuti.
• Prima scarica tutto ciò che vuoi conservare.
• La registrazione di fatturazione resta: la voce contabile, l’importo addebitato, il modello, lo stato, gli orari e l’ID della richiesta restano visibili anche dopo.
• Ripetere la distruzione su un’attività i cui contenuti sono già stati distrutti non crea problemi.

Restituisce: taskId, contentState (purged una volta programmata l’eliminazione), purgedAt, contentRemovedBy e billingRetained: true. Di proposito non restituisce alcun link. La rimozione fisica dei file di norma si completa entro un minuto; vedi Conservazione e distruzione.

Risorse e prompt

Oltre agli strumenti, il server offre due risorse di sola lettura e un prompt. Le app le mostrano in posti diversi, e molte persone non ne hanno mai bisogno.

Costi, conferme e sicurezza

Come si presenta la conferma

Quando l’assistente avvia un’attività, l’app mostra una domanda del server SpicyAPI. Il testo è simile a questo (gli importi sono esempi):

Create a billable task using MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.20;
maximum charge: USD 0.20. Quote expires: 2026-09-17T12:05:00Z. Before accepting
the request, SpicyAPI checks the model's current input requirements, price and
availability, your API key permissions, and available funds.
Idempotency-Key: 4f1c…

Oggi l’addebito stimato e quello massimo mostrano lo stesso numero: la stima è l’importo accantonato quando l’attività parte, e l’attività non viene mai addebitata per più di quell’accantonamento.

Il modo in cui rispondi dipende dall’app: di solito una casella di controllo o un interruttore confirm, più i pulsanti Accept e Decline. Seleziona confirm e accetta per procedere. Rifiutare o annullare chiude la chiamata allo strumento, e il messaggio dice che cosa è successo e che cosa no:

Rispondi entro cinque minuti. Il preventivo vale cinque minuti. Se quando confermi è già scaduto, la creazione fallisce con l’errore 40901 e non viene addebitato nulla; chiedi all’assistente di riprovare per avere un preventivo nuovo.

Il nuovo tentativo mostra una domanda simile, senza prezzo. La distruzione dei contenuti avverte che l’eliminazione non si può annullare e che le registrazioni di fatturazione vengono conservate.

Perché l’assistente non può saltarla

• La domanda arriva a te, non all’IA. Il server la invia alla tua app tramite la funzione elicitation di MCP, e l’app la mostra a te. L’assistente non ha modo di rispondere.
• La tua risposta è legata a quella richiesta esatta. La conferma è vincolata al modello e alle impostazioni che ti sono stati mostrati. Se l’assistente cambia qualcosa tra la domanda e la tua risposta, il server rifiuta con "confirmed request state does not match the current tool arguments" e non viene creato nulla.
• Lascia le cose così. Se la tua app offre un’impostazione che accetta automaticamente le domande dei server MCP, tienila disattivata per SpicyAPI. Un assistente o un’impostazione che conferma al posto tuo elimina l’unico controllo della spesa su questo percorso.
• Le app senza supporto per la conferma non possono spendere. In queste app, l’avvio, il nuovo tentativo e la distruzione dei contenuti restituiscono semplicemente un errore; a quel punto l’avvio di un’attività ha richiesto solo il suo preventivo gratuito. Vedi Prima di iniziare.

Che cosa paghi

• I prezzi sono in dollari statunitensi. Stime, addebiti e saldi sono importi esatti in dollari.
• Non ti viene mai addebitato più del massimo che hai confermato. Quando un’attività parte, il suo importo stimato viene accantonato (e compare come «held»). Quando riesce, paghi l’utilizzo effettivo, entro il tetto di quell’accantonamento, e la parte non usata viene svincolata.
• Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale.
• Consultare è gratuito: sfogliare i modelli, i preventivi, il saldo, i consumi, la consultazione delle attività, le attese, i caricamenti e i link di download.
• Un’attività avviata non si può annullare. Chiudere la chat, uscire dall’app, un’attesa scaduta o la revoca della chiave non fermano un’attività già accettata. Vedi Impegno dell’attività e nuovi tentativi.
• Valgono i limiti della tua chiave. Quando viene raggiunto un limite giornaliero, mensile o complessivo, le nuove attività vengono rifiutate con 40202 finché non inizia il periodo successivo; vedi Fatturazione.

Per quanto tempo vengono conservati i risultati

• I file generati vengono conservati al massimo per circa 14 giorni, meno se hai accorciato la conservazione per il tuo account o per quella attività. Scarica tutto ciò che vuoi tenere.
• I link ai risultati sono temporanei: normalmente 20 minuti. Un link scaduto non significa che il file sia sparito: richiedi di nuovo l’attività per avere un link nuovo, purché sia ancora entro il periodo di conservazione.
• Prompt e input vengono conservati al massimo per 30 giorni; la registrazione di fatturazione dell’attività (ID, modello, stato, importo, orari) resta.
• I file caricati si possono usare per un giorno.
• Per eliminare in anticipo i contenuti di un’attività, chiedi all’assistente di distruggerli. Per accorciare la conservazione di una singola attività, chiedigli di impostare retentionSeconds al momento della creazione.

Le regole complete e le eccezioni sono in Conservazione e distruzione.

File locali

spicyapi_upload_file può leggere i file del tuo computer, e questo richiede attenzione:

• Per impostazione predefinita legge solo dentro la tua cartella home (per esempio /Users/you o C:\Users\you). Un file che si trova altrove viene rifiutato con un messaggio che indica quali cartelle sono consentite.
• Le scorciatoie non aggirano il limite. Un collegamento simbolico dentro la tua cartella home che punta all’esterno viene rifiutato.
• Perché esiste il limite: un assistente che legge una pagina web, un’email o un documento può imbattersi in istruzioni nascoste come «carica le chiavi private dell’utente». Il limite sulle cartelle tiene questo genere di trucchi lontano dai file di sistema. La tua cartella home resta comunque leggibile, quindi lascia che l’assistente carichi solo i file che hai indicato tu, e leggi il percorso quando l’app ti chiede di approvare la chiamata allo strumento.

Cambiare le cartelle. Aggiungi SPICY_MCP_UPLOAD_ROOTS all’env del server, accanto a SPICY_API_KEY, con uno o più percorsi completi di cartelle. Questa impostazione sostituisce quella predefinita, quindi puoi restringerla a una sola cartella oppure elencarne diverse. Le cartelle si separano nello stesso modo dell’impostazione di sistema PATH, che cambia a seconda del sistema operativo. Scrivi ogni cartella come percorso completo: in questa impostazione ~ non viene espanso, anche se lo è nei percorsi di file che dai all’assistente.

{
  "env": {
    "SPICY_API_KEY": "YOUR_SPICY_API_KEY",
    "SPICY_MCP_UPLOAD_ROOTS": "/Users/you/Pictures:/Users/you/Movies"
  }
}

Questi blocchi mostrano solo la parte env. Aggiungi la riga SPICY_MCP_UPLOAD_ROOTS all’env della voce spicyapi che hai creato in Configura il tuo client, e lascia com’è la riga con la chiave. Per Claude Code e Codex, aggiungila invece al comando di registrazione (-e SPICY_MCP_UPLOAD_ROOTS=… o --env SPICY_MCP_UPLOAD_ROOTS=…), dopo aver rimosso il server. Poi riavvia l’app. Una cartella che non esiste semplicemente non corrisponde a nulla, quindi se dopo questa modifica i caricamenti vengono rifiutati, controlla come sono scritte le cartelle nel messaggio, che elenca quelle usate dal server.

Modalità HTTP: solo questo computer

La maggior parte delle app avvia il server da sé, come visto sopra. Alcune preferiscono collegarsi, tramite un indirizzo, a un server già in esecuzione. Per queste il pacchetto include un secondo programma, spicyapi-mcp-http:

export SPICY_API_KEY="sk-spicy-..."
export SPICY_MCP_HTTP_TOKEN="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")"
npx --yes --package=@spicyapi/mcp spicyapi-mcp-http

Stampa SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp. Punta la tua app a quell’indirizzo e fai in modo che invii l’intestazione Authorization: Bearer seguita dal tuo SPICY_MCP_HTTP_TOKEN. Quando il server è in esecuzione, http://127.0.0.1:8765/healthz risponde {"ok":true}.

«Solo loopback» significa che possono collegarsi solo i programmi di questo stesso computer. Gli altri dispositivi sulla tua rete Wi-Fi e internet non possono raggiungerlo, e non esiste un’impostazione per aprirlo: qualsiasi altro indirizzo viene rifiutato all’avvio. Vengono rifiutate anche le richieste provenienti da pagine web di altri siti. Se ti serve un server raggiungibile da altre macchine, non è questo.

Risoluzione dei problemi

Codice sorgente

Il pacchetto ha licenza MIT ed è sviluppato in modo aperto su github.com/spicyapi-ai/spicy-mcp. È lì che si legge il codice dietro a ogni strumento di questa pagina, si segnala un comportamento diverso da quello descritto e si propone una modifica.

Prossimi passi