> ## Documentation Index > Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Connetti Krea ad agenti compatibili con MCP così possono scoprire i modelli, ispezionare gli schemi e generare immagini o video dal tuo workspace. 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](https://www.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](/developers/api-keys-and-billing) 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: ```bash theme={null} 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 1. Apri **Settings** > **MCP servers** in Codex. 2. Aggiungi un nuovo server. 3. Seleziona **Streamable HTTP** come trasporto. 4. Incolla l'URL del server: ```text theme={null} https://api.krea.ai/mcp ``` 5. 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`: ```json theme={null} { "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: ```text theme={null} 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](/developers/deprecations) 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](/developers/job-lifecycle) per le regole e le implicazioni di fatturazione (i job annullati non vengono fatturati). Esempio di prompt: ```text theme={null} 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: ```bash theme={null} # 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. ## Widget UI di MCP Apps Le chiamate agli strumenti di generazione e di node app allegano una risorsa UI di [MCP Apps](https://modelcontextprotocol.io/). 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](https://www.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 Crea token API e gestisci il saldo API per le richieste autenticate con token. Prova le richieste nell'app Krea prima di chiedere a un agente di eseguirle. Scopri come MCP espone i metadati di migrazione dei modelli. Esplora gli schemi degli endpoint e i parametri dei modelli.