MCP

Krea espone un server Model Context Protocol (MCP) gestito per agenti e assistenti di programmazione. Usalo quando vuoi che un client compatibile con MCP chiami Krea direttamente invece di scrivere richieste API a mano.

Non ti serve una chiave API per connetterti. Aggiungi https://api.krea.ai/mcp come URL del server MCP, quindi accedi con il tuo account Krea tramite il flusso OAuth del tuo client.

Dettagli del server

Impostazione	Valore
Trasporto	Streamable HTTP
URL	`https://api.krea.ai/mcp`
Autenticazione	OAuth

La fatturazione dipende da come ti autentichi:

Metodo di autenticazione	Fonte di fatturazione
OAuth	Le unità di calcolo del workspace che selezioni durante il consenso
Token API	Il saldo API separato del tuo workspace

Autenticazione

La maggior parte dei client MCP usa OAuth automaticamente. Quando il client ti chiede di connetterti, segui il flusso di accesso nel browser e autorizza Krea.

Scegli un workspace durante il consenso

La schermata di consenso OAuth include un selettore di Workspace che elenca tutti i workspace a cui appartieni. Il tuo workspace predefinito è preselezionato; scegline uno diverso se vuoi che questa sessione MCP venga eseguita altrove (ad esempio, un workspace di studio condiviso invece del tuo personale). Il workspace che selezioni è vincolato alla sessione OAuth e determina:

Fatturazione. Le unità di calcolo vengono detratte dal workspace selezionato, non solo dall’account con cui hai effettuato l’accesso.
Ambito degli asset. I file caricati tramite strumenti come upload_asset vengono salvati nel workspace vincolato, e gli strumenti che richiedono un upload (ad esempio, get_upload_url) funzionano solo dopo che un workspace è stato vincolato.

Per cambiare il workspace vincolato in seguito, disconnetti Krea nel tuo client MCP e riconnettiti — vedrai di nuovo il selettore.

Le sessioni OAuth legacy create prima del rilascio del selettore di workspace non hanno un vincolo esplicito. Tali sessioni ricadono sul workspace predefinito del tuo account. Riconnettiti per vincolare la sessione a un workspace specifico.

Se il tuo client MCP non supporta OAuth, puoi autenticarti con un token API:

Chiave dell’header	Valore dell’header
`Authorization`	`Bearer KREA_API_TOKEN`

Sostituisci KREA_API_TOKEN con un token da krea.ai/app/api/tokens. Solo i proprietari e gli amministratori del workspace possono creare token API. L’utilizzo con token API viene addebitato al saldo API del tuo workspace, allo stesso modo delle chiamate API dirette. Vedi Chiavi API e fatturazione per i dettagli sul saldo API.

Conserva le credenziali MCP con token API allo stesso modo in cui conservi le chiavi API. Non fare commit di file di configurazione MCP che contengono token reali.

Claude Code

Esegui questo comando nel tuo terminale:

claude mcp add --transport http krea-ai https://api.krea.ai/mcp

Accedi con il tuo account Krea quando Claude Code ti chiede di connetterti. Riavvia Claude Code o ricarica i tuoi server MCP dopo aver aggiunto il server.

Codex

Apri Settings > MCP servers in Codex.
Aggiungi un nuovo server.
Seleziona Streamable HTTP come trasporto.
Incolla l’URL del server:

https://api.krea.ai/mcp

Salva il server e accedi con il tuo account Krea quando Codex ti chiede di connetterti.

Cursor

Apri la palette dei comandi, cerca Open MCP settings, quindi aggiungi questa voce a mcp.json:

{
  "mcpServers": {
    "krea-ai": {
      "url": "https://api.krea.ai/mcp"
    }
  }
}

Riavvia Cursor dopo aver salvato il file, quindi accedi con il tuo account Krea quando Cursor ti chiede di connetterti.

Usare Krea tramite MCP

Una volta connesso, chiedi al tuo agente di elencare i modelli Krea o di ispezionare lo schema di un modello prima di generare. Gli ID dei modelli corrispondono ai percorsi API usati nel resto della documentazione per sviluppatori, come image/krea/krea-2/medium o video/google/veo-3.1. Per esempio:

List the available Krea image models, then generate an image with Krea 2 using a 16:9 aspect ratio.

Se un modello è deprecato, Krea restituisce i metadati di deprecazione tramite la scoperta dei modelli MCP. Vedi Deprecazioni per le linee guida sulla migrazione.

Strumenti

Il server MCP di Krea espone strumenti che corrispondono all’API pubblica. Il tuo agente li scopre automaticamente tramite tools/list; quelli più comuni sono:

Strumento	Cosa fa
`list_models`	Elenca i modelli di immagine e video disponibili.
`get_model_schema`	Ispeziona lo schema di input di un modello prima di generare.
`generate`	Invia un job di generazione di immagini o video.
`execute_node_app`	Esegue una node app.
`get_job`	Recupera lo stato attuale e l’output di un job tramite il `jobId`.
`cancel_job`	Annulla un job in corso e lo rimuove dall’elenco dei tuoi job.
`get_upload_url`	Richiede un URL prefirmato di breve durata per caricare un file locale da usare come input di un modello.

Gli output degli strumenti di generazione e di node app includono il job_id del job inviato insieme al payload del job. Passa quell’ID a get_job per controllare lo stato, oppure a cancel_job per fermare un job di cui non hai più bisogno.

Annullare un job

cancel_job chiama DELETE /jobs/{id} dietro le quinte e restituisce { "job_id": "...", "deleted": true } in caso di successo. L’annullamento ha effetto solo mentre il job si trova in uno stato non terminale — vedi Ciclo di vita del job per le regole e le implicazioni di fatturazione (i job annullati non vengono fatturati). Esempio di prompt:

Cancel job 7f3c9b1a-… because the prompt was wrong.

Fornire input multimediali

Qualsiasi input di un modello che accetta un URL multimediale (per esempio start_image, image_style_references[].url o reference_images) accetta una di tre forme:

Un URL esterno — un link https:// pubblicamente raggiungibile a un file di immagine, video, audio o modello 3D.
Un data URI in base64 — per esempio data:image/png;base64,iVBORw0KGgo….
Un URL di asset caricato — l’URL restituito dopo aver caricato un file locale su Krea.

Le liste di URL separate da virgola non sono supportate. Passa ogni input come campo o elemento di array a sé stante.

Caricare un file locale con `get_upload_url`

Quando il file che vuoi usare si trova sul tuo computer locale e non è già ospitato da qualche parte, chiedi al tuo agente di chiamare get_upload_url. Lo strumento restituisce un URL prefirmato valido per tre ore. Il tuo client esegue quindi un POST del file a quell’URL come multipart/form-data con un singolo campo file, e il corpo della risposta contiene un URL di asset che puoi passare a una successiva chiamata a generate. Esempio di flusso:

# 1. Ask the agent to call get_upload_url through MCP. It returns something like:
#    https://api.krea.ai/public-api/assets/presigned/...

# 2. POST the local file to that presigned URL.
curl -X POST "$UPLOAD_URL" -F "file=@/path/to/image.png"

# 3. The response body contains the asset URL. Use it in the next generate call,
#    for example as start_image or image_style_references[].url.

Se il POST di caricamento fallisce a causa di egress di rete limitato, aggiungi api.krea.ai alla lista di domini consentiti del tuo client. L’URL prefirmato viene servito dallo stesso host del resto dell’API pubblica.

Se il tuo file è già accessibile tramite un URL pubblico o puoi codificarlo come data URI in base64, salta get_upload_url e passa direttamente quel valore nell’input di generazione. Le chiamate agli strumenti di generazione e di node app allegano una risorsa UI di MCP Apps. I client MCP che supportano MCP Apps renderizzano un widget interattivo del risultato del job in linea con la risposta dello strumento, che include:

Un riquadro di caricamento dimensionato in base al rapporto d’aspetto del job mentre il job è in coda o in elaborazione.
Polling automatico di get_job in modo che il widget si aggiorni man mano che il job avanza, senza che l’agente debba chiamare get_job da solo.
Pulsanti di azione per riprovare la generazione o annullare il job dall’interno del widget.
Uno slider di confronto prima/dopo a schermo intero per i risultati di enhance.

Il widget viene esposto come la risorsa ui://krea-public-api/job-result-frame ed è collegato automaticamente — non è richiesta alcuna configurazione del client. I client che non supportano MCP Apps semplicemente ignorano la risorsa e ricadono sull’output strutturato dello strumento. Poiché il widget fa il polling per te, preferisci la generazione asincrona (l’impostazione predefinita) quando vuoi che la UI mostri l’avanzamento. Usa la modalità sincrona solo quando l’utente chiede esplicitamente di attendere il risultato finale nella risposta dello strumento.

Risoluzione dei problemi

Problema	Soluzione
L’autenticazione fallisce	Riconnetti il server MCP e completa il flusso OAuth di Krea nel tuo browser. Se usi un token API, conferma che l’header sia esattamente `Authorization: Bearer KREA_API_TOKEN` e che il token non sia stato revocato.
Il client non riesce a connettersi	Verifica che il client sia configurato per Streamable HTTP e usi `https://api.krea.ai/mcp`.
La generazione viene rifiutata per fatturazione	Se ti sei connesso con OAuth, controlla le unità di calcolo sul workspace che hai selezionato durante il consenso — riconnettiti se devi vincolare la sessione a un workspace diverso. Se ti sei connesso con un token API, aggiungi saldo API su krea.ai/app/api.
La chiamata al modello fallisce	Chiedi al tuo agente di ispezionare lo schema del modello prima di riprovare. Le richieste MCP usano gli stessi input dei modelli dell’API.

Prossimi passi

Chiavi API e fatturazione

Crea token API e gestisci il saldo API per le richieste autenticate con token.

Playground interattivo

Prova le richieste nell’app Krea prima di chiedere a un agente di eseguirle.

Deprecazioni

Scopri come MCP espone i metadati di migrazione dei modelli.

API dei modelli

Esplora gli schemi degli endpoint e i parametri dei modelli.

Per iniziare

Krea 2

Concetti fondamentali

Esempi di codice

Dettagli del server

Autenticazione

Scegli un workspace durante il consenso

Claude Code

Codex

Cursor

Usare Krea tramite MCP

Strumenti

Annullare un job

Fornire input multimediali

Caricare un file locale con `get_upload_url`

Widget UI di MCP Apps

Risoluzione dei problemi

Prossimi passi

Chiavi API e fatturazione

Playground interattivo

Deprecazioni

API dei modelli

​Dettagli del server

​Autenticazione

​Scegli un workspace durante il consenso

​Claude Code

​Codex

​Cursor

​Usare Krea tramite MCP

​Strumenti

​Annullare un job

​Fornire input multimediali

​Caricare un file locale con get_upload_url

​Widget UI di MCP Apps

​Risoluzione dei problemi

​Prossimi passi

Chiavi API e fatturazione

Playground interattivo

Deprecazioni

API dei modelli

Dettagli del server

Autenticazione

Scegli un workspace durante il consenso

Claude Code

Codex

Cursor

Usare Krea tramite MCP

Strumenti

Annullare un job

Fornire input multimediali

Caricare un file locale con `get_upload_url`

Widget UI di MCP Apps

Risoluzione dei problemi

Prossimi passi