MCP server

Samsa gestisce un MCP server (Model Context Protocol) remoto, così qualsiasi client compatibile con MCP — Claude, ChatGPT, Claude Code, Cursor, n8n e altri — guida lo studio Samsa della tua organizzazione come un insieme di strumenti. Genera immagini con i tuoi modelli style, object, person e setting addestrati, esegui Magic Edit, produci video e controlla il tuo saldo credits — tutto dall’interno dell’app o dell’agent con cui già lavori. Niente da installare: è un solo URL e un accesso.

Genera immagini

Trasforma un prompt in immagini, componendo facoltativamente i modelli style, object, person e setting addestrati dalla tua organizzazione e le palette di colori.

Magic Edit

Modifica un’immagine esistente da un prompt — con o senza maschera — e riusa gli stessi modelli addestrati per risultati fedeli al tuo brand.

Crea video

Produci video da un frame iniziale, da testo o da testo stilizzato con i tuoi modelli addestrati — tutto come una singola chiamata a uno strumento.

Traccia job e credits

Interroga qualsiasi job fino al completamento e leggi il saldo credits rimanente della tua organizzazione — le letture sono sempre gratuite.

Server URL — aggiungi questo unico endpoint a qualsiasi client MCP:

https://api.samsa.ai/mcp

È un server remoto su Streamable HTTP — non c’è nulla da installare, nessun processo locale da eseguire e un singolo path (/mcp, senza barra finale) serve entrambe le modalità di autenticazione. Il transport è stateless: ogni chiamata a uno strumento restituisce una singola risposta JSON e gli strumenti di generazione restituiscono un id del job immediatamente, così niente mantiene aperto uno stream di lunga durata.

Connettiti in tre passaggi

Ottieni le tue credenziali

Le app interattive — Claude e ChatGPT — accedono con OAuth; tu approvi una schermata di consenso nell’app Samsa e non incolli mai una chiave. I client headless — Claude Code, Cursor, n8n, SDK — usano una API key creata in Settings → API Keys.

Aggiungi il server

Punta il tuo client a https://api.samsa.ai/mcp. Non c’è nulla da installare né alcun processo locale — consulta il tuo client qui sotto per l’esatta configurazione una tantum.

Inizia a creare

Il tuo client elenca i nove strumenti Samsa. Chiedigli di generare un’immagine, eseguire un Magic Edit, creare un video oppure creare e aggiornare i tuoi modelli addestrati — invia ogni job e interroga quelli asincroni fino al completamento al posto tuo.

Autenticazione

L’endpoint MCP accetta due tipi di credenziali sullo stesso URL. Scegli quella che corrisponde al tuo client:

Modalità	Ideale per	Come funziona
OAuth 2.1	App interattive — Claude (web/desktop), ChatGPT	Accedi con il tuo account Samsa e approvi una schermata di consenso nell’app. Il client gestisce il token; tu non incolli mai una chiave.
API key (`samsa_sk_…`)	Client headless — Claude Code, Cursor, VS Code, n8n, SDK	Invia `Authorization: Bearer samsa_sk_…`. Crea le chiavi in Settings → API Keys; gli scope della chiave regolano quali strumenti può chiamare.

Entrambe agiscono per un’organizzazione: i credits vengono prelevati dal pool di quell’organizzazione e gli asset generati appaiono nell’app sotto l’account connesso. Consulta Autenticazione per capire come funzionano chiavi, scope e organizzazioni.

L’accesso OAuth segue il flusso MCP standard: il client scopre il server di autorizzazione di Samsa dal challenge 401, si registra dinamicamente (PKCE, nessun client secret) e ti fa passare attraverso una schermata di consenso prima di scambiare un access token di breve durata. Il flusso interattivo di consenso via browser è in early access — se un accesso non si completa, faccelo sapere a support@samsa.ai.

Strumenti

Il server espone nove strumenti. Le quattro letture (list_models, get_model, get_job_status, get_credit_balance) e i due strumenti di gestione dei modelli (create_model, update_model) sono gratuiti; i tre strumenti di generazione costano credits dal pool della tua organizzazione, alle stesse tariffe dell’app e della REST API.

Strumento	Cosa fa	Scope	Costo
`list_models`	Elenca i modelli addestrati pronti della tua organizzazione (id, nome, categoria, thumbnail).	`models.read`	Gratis
`get_model`	Dettaglio completo di un modello — stato, immagini di riferimento, prompt predefinito, trigger word.	`models.read`	Gratis
`create_model`	Addestra un nuovo modello da 1–10 immagini di riferimento (async).	`models.write`	Gratis
`update_model`	Aggiorna nome, prompt predefinito e/o l’istruzione sempre applicata di un modello.	`models.write`	Gratis
`generate_image`	Genera immagini da un prompt, componendo facoltativamente i tuoi modelli addestrati.	`images.generate`	5 × output × risoluzione
`edit_image`	Magic Edit — modifica un’immagine da un prompt.	`images.edit`	5 per output
`generate_video`	Genera video da un frame iniziale, da testo o da testo stilizzato con i tuoi modelli.	`videos.generate`	5 / secondo × engine × risoluzione × audio
`get_job_status`	Interroga un job di immagine, modifica, video o modello inviato per stato e risultati.	scope dello strumento che ha inviato	Gratis
`get_credit_balance`	Leggi il saldo credits rimanente della tua organizzazione e il periodo di fatturazione.	`usage.read`	Gratis

Una chiamata a uno strumento rifiutata per uno scope mancante restituisce un errore strutturato dello strumento (non un crash) che nomina lo scope di cui ha bisogno. Le chiavi vengono create con tutti gli scope per impostazione predefinita; un admin può restringere o ampliare una chiave in Settings → API Keys.

Parametri

list_models(category?)

category (facoltativo) — filtra a uno tra style, object, person, setting.

Restituisce i modelli pronti della tua organizzazione con id, name, category e un thumbnail_url presigned. Usa gli id o i nomi come style_id / object_ids / person_ids / setting_ids in generate_image e generate_video — un nome viene risolto a un modello visibile a te.

get_model(model_id)

model_id (obbligatorio) — l’id del modello.

Restituisce il dettaglio completo: stato, prontezza, URL presigned delle immagini di riferimento, il prompt predefinito e le trigger word.

create_model(name, category, images, …)

name (obbligatorio) — il nome del modello.
category (obbligatorio) — uno tra style, object, person, setting.
images (obbligatorio) — 1–10 immagini di riferimento. Ciascuna è o un URL https pubblico oppure un data URI base64 inline (data:image/png;base64,…) — image/jpeg, image/png o image/webp, ≤ 10 MB ciascuna.
instruction (facoltativo) — la guida sempre applicata del modello (≤ 8000 caratteri), iniettata come direttiva obbligatoria (“MUST FOLLOW”) in ogni generazione che compone il modello. Vedi Addestramento di modelli.
webhook_url (facoltativo) — un URL https notificato una volta quando l’addestramento raggiunge uno stato terminale.

Asincrono — restituisce subito { id, status: "pending", estimated_credits }; interroga get_job_status(kind="model", id=…) (che richiede anche lo scope models.read) finché non è completed o failed, poi usa l’id del modello in generate_image / generate_video. Gratis — la creazione del modello non deduce credits. Gli upload presigned di file di grandi dimensioni sono solo REST (non esposti via MCP) — usa POST /models/prepare per quelli.

update_model(model_id, …)

model_id (obbligatorio) — il modello da aggiornare.
name (facoltativo) — un nuovo nome del modello.
default_prompt (facoltativo) — un nuovo prompt predefinito.
instruction (facoltativo) — la guida sempre applicata del modello (≤ 8000 caratteri). Invia una stringa vuota per cancellarla.

Fornisci almeno uno tra name, default_prompt o instruction; i campi omessi restano invariati. Sincrono — restituisce subito il modello aggiornato completo (stessa forma di get_model). Gratis.

generate_image(prompt, …)

prompt (obbligatorio) — il prompt testuale.
style_id, object_ids, person_ids, setting_ids (facoltativi) — id o nomi dei modelli addestrati da list_models da comporre (un nome viene risolto a un modello visibile a te).
color_palette (facoltativo) — una palette di colori da applicare, indicata con il suo nome o id (come i riferimenti ai modelli addestrati).
num_outputs (1–4, predefinito 1), aspect_ratio (predefinito "1:1"), resolution (predefinito "1K"; 1K / 2K / 4K).

aspect_ratio accetta 1:1 (predefinito), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 e 8:1.Asincrono — restituisce { id, status: "pending", estimated_credits } immediatamente. Costo: 5 × num_outputs × risoluzione (1K ×1, 2K ×2, 4K ×4), dedotto all’invio.

edit_image(prompt, …)

prompt (obbligatorio) — come modificare l’immagine.
Esattamente uno tra image_id (un’immagine nel tuo contesto Samsa) o image_url (un URL https pubblico).
style_id, object_ids, person_ids, setting_ids (facoltativi) — id o nomi dei modelli addestrati da list_models da riusare per modifiche fedeli al tuo brand (un nome viene risolto a un modello visibile a te), alla pari con generate_image.
color_palette (facoltativo) — una palette di colori da applicare, indicata con il suo nome o id.
engine (facoltativo) — nano_banana_pro (predefinito), gemini o kontext. Fornire un qualsiasi riferimento a un modello addestrato o una palette di colori forza nano_banana_pro.

Asincrono — restituisce { id, status: "pending", estimated_credits }. Costo: 5 credits per output (nano_banana_pro scala con la risoluzione: 1K ×1, 2K ×2, 4K ×4), dedotto all’invio.

generate_video(mode, …)

mode (obbligatorio) — uno tra:
- image_to_video — anima un frame iniziale. Richiede esattamente uno tra image_id / image_url; end_image_url facoltativo su engine capaci di gestire il frame finale; prompt facoltativo.
- text_to_video — richiede prompt.
- text_to_video_styled — richiede prompt e style_id; object_ids / person_ids / setting_ids facoltativi, più una color_palette facoltativa (nome o id).
engine (predefinito veo_3_1_lite), duration (predefinito: la durata più breve supportata dall’engine, in secondi), aspect_ratio (predefinito "16:9"; anche 9:16, 1:1).

Asincrono — restituisce { id, status: "pending", estimated_credits }. Costo: moltiplicatori 5 / secondo × engine × risoluzione × audio; la modalità stilizzata aggiunge un forfait di 10 per l’immagine intermedia. Consulta prezzi.

get_job_status(kind, id)

kind (obbligatorio) — image_generation, image_edit, video o model.
id (obbligatorio) — l’id del job o del modello restituito da uno strumento di invio.

Restituisce lo stato (pending → processing → completed / failed) e, una volta completed, gli URL presigned del risultato validi per 24 ore. Richiede lo scope dello strumento che ha inviato (models.read per kind: "model").Per un job di immagine completato (image_generation o image_edit), la risposta include anche l’immagine stessa come anteprima inline ridimensionata — così i client MCP possono visualizzarla direttamente — insieme al link all’immagine a piena risoluzione. L’anteprima è una copia a risoluzione ridotta per una visualizzazione rapida; recupera il link per l’asset originale a piena risoluzione.

get_credit_balance()

Nessun parametro. Restituisce il totale disponibile della tua organizzazione, i credits del piano, i credits di top-up e il periodo di fatturazione corrente.

Il pattern asincrono

I tre strumenti di generazione sono asincroni — accodano un job e restituiscono subito, così il tuo client non si blocca mai in attesa di un rendering.

Invio

Chiama generate_image, edit_image o generate_video. Restituisce { id, status: "pending", estimated_credits, next_step } in millisecondi e i credits stimati vengono dedotti dal pool della tua organizzazione all’invio.

Interrogazione

Chiama get_job_status(kind=…, id=…) con l’id che hai ricevuto. Lo stato passa da pending → processing → completed (o failed). I job di immagine tipicamente finiscono da 30 secondi a due minuti; i video da uno a cinque.

Raccolta

Una volta completed, la risposta contiene gli URL presigned del risultato validi per 24 ore. Se un job termina failed per un problema di Samsa, i credits vengono automaticamente rimborsati allo stesso pool.

Il server lo comunica ai modelli connessi da sé: ogni risultato di invio include una stringa next_step con l’esatta chiamata get_job_status da fare, così un agent capace interroga senza prompt aggiuntivi.

Configura il tuo client

Aggiungi https://api.samsa.ai/mcp al tuo client qui sotto. Claude e ChatGPT accedono con OAuth; ogni altro client si autentica con una API key (Authorization: Bearer samsa_sk_…).

Gli snippet con API key qui sotto mostrano la chiave inline per leggibilità. In qualsiasi configurazione che viene committata o condivisa, non memorizzare una chiave reale — usa l’interpolazione delle variabili d’ambiente del tuo client (mostrata per Claude Code, Cursor e VS Code) oppure mantieni la configurazione a livello utente. Una samsa_sk_… trapelata va revocata immediatamente.

OAuth · early access — faccelo sapere se non funzionaClaude (web e desktop) si connette agli MCP server remoti come custom connector:

Aggiungi il connector

Apri Settings → Connectors → Add custom connector e imposta l’URL a https://api.samsa.ai/mcp.

Accedi

Claude apre l’accesso OAuth di Samsa; accedi e approva la schermata di consenso. La lista degli strumenti di Claude mostra poi gli strumenti Samsa.

Le etichette esatte dei menu variano a seconda della versione — l’essenziale è il flusso del custom connector e il server URL di Samsa. Claude web chiama /mcp dal browser con Origin: https://claude.ai, che Samsa consente, così discovery e accesso funzionano senza configurazione aggiuntiva. Su desktop, segui le istruzioni correnti di Anthropic per i connector e usa lo stesso server URL.

OAuth · early access — faccelo sapere se non funziona

Abilita la developer mode

In ChatGPT, apri Settings → Apps & Connectors e abilita la developer mode.

Aggiungi la connessione

Aggiungi una connessione app / MCP con l’URL https://api.samsa.ai/mcp.

Accedi

ChatGPT esegue l’accesso e il consenso OAuth 2.1; approvalo per esporre gli strumenti Samsa.

Le etichette esatte dei menu variano a seconda della versione — l’essenziale è abilitare la developer mode e aggiungere il server URL di Samsa. Le connessioni MCP personalizzate richiedono un piano ChatGPT che includa la developer mode / connector; la disponibilità cambia nel tempo, quindi controlla il tuo piano se l’opzione manca. ChatGPT chiama /mcp con Origin: https://chatgpt.com (o https://chat.openai.com), entrambi consentiti da Samsa.

API key · verificatoAggiungi il server con il transport HTTP e un header Bearer:

claude mcp add --transport http samsa https://api.samsa.ai/mcp \
  --header "Authorization: Bearer samsa_sk_..."

Per impostazione predefinita questo registra il server solo per il tuo uso (local scope). Per condividerlo con il tuo team, aggiungi --scope project e Claude Code scrive un file .mcp.json di progetto. Poiché quel file viene committato, tieni la chiave fuori da esso — Claude Code espande le variabili d’ambiente in headers:

{
  "mcpServers": {
    "samsa": {
      "type": "http",
      "url": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer ${SAMSA_API_KEY}" }
    }
  }
}

Conferma la connessione con claude mcp get samsa — dovrebbe riportare Connected.Preferisci OAuth? (early access — faccelo sapere se non funziona) Esegui claude mcp add --transport http samsa https://api.samsa.ai/mcp senza l’header e completa l’accesso OAuth al primo uso. La configurazione con header qui sopra è il percorso verificato; la variante OAuth senza chiave è ancora in fase di verifica.

API key · early access — faccelo sapere se non funzionaAggiungi a ~/.cursor/mcp.json (globale) o al .cursor/mcp.json di progetto. Cursor interpola le variabili d’ambiente in headers, quindi fai riferimento alla chiave invece di inserirla inline in un file condiviso:

{
  "mcpServers": {
    "samsa": {
      "url": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:SAMSA_API_KEY}" }
    }
  }
}

API key · early access — faccelo sapere se non funzionaAggiungi a .vscode/mcp.json:

{
  "servers": {
    "samsa": {
      "type": "http",
      "url": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer samsa_sk_..." }
    }
  }
}

Non committare una chiave reale in un file di workspace. VS Code supporta le variabili ${input:...} e la configurazione MCP a livello utente — usa una di queste così il segreto non viene incluso nel controllo di versione con il tuo progetto.

Windsurf · early access

(early access — faccelo sapere se non funziona)Aggiungi a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "samsa": {
      "serverUrl": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer samsa_sk_..." }
    }
  }
}

Codex (OpenAI) · early access

(early access — faccelo sapere se non funziona)Aggiungi a ~/.codex/config.toml:

[mcp_servers.samsa]
url = "https://api.samsa.ai/mcp"
http_headers = { Authorization = "Bearer samsa_sk_..." }

n8n — MCP Client node · early access

(early access — faccelo sapere se non funziona)Nel nodo MCP Client, imposta:

Endpoint — https://api.samsa.ai/mcp
Transport — HTTP Streamable
Authentication — Header Auth con Authorization: Bearer samsa_sk_...

n8n gira lato server (nessun header Origin del browser), quindi si connette senza alcuna configurazione aggiuntiva.

Gemini CLI · early access

(early access — faccelo sapere se non funziona)Aggiungi un MCP server HTTP a ~/.gemini/settings.json. I nomi delle chiavi di configurazione differiscono tra le versioni di Gemini CLI — verifica rispetto alla documentazione MCP corrente di Gemini CLI — ma la forma è l’URL di Samsa più un header Bearer:

{
  "mcpServers": {
    "samsa": {
      "httpUrl": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer samsa_sk_..." }
    }
  }
}

Microsoft Copilot Studio · early access

(early access — faccelo sapere se non funziona)Copilot Studio si connette agli MCP server tramite una custom connector / MCP connection. Nel maker portal, crea una connessione MCP personalizzata che punta a https://api.samsa.ai/mcp e fornisci l’header Authorization: Bearer samsa_sk_... come credenziale della connessione. La formulazione esatta del portale cambia nel tempo — segui la guida corrente di Microsoft “connect to an MCP server” e usa l’URL e l’header di Samsa qui sopra.

Provalo — MCP Inspector · early access

(early access — faccelo sapere se non funziona)Per verificare il server da uno strumento neutrale, usa l’ MCP Inspector. Guidalo dalla GUI (o da un file di configurazione) con il transport Streamable-HTTP:

{
  "mcpServers": {
    "samsa": {
      "type": "streamable-http",
      "url": "https://api.samsa.ai/mcp",
      "headers": { "Authorization": "Bearer samsa_sk_..." }
    }
  }
}

L’Inspector usa lo stesso transport Streamable-HTTP contro cui Samsa verifica e gira su http://localhost:6274, che Samsa consente. Usalo per percorrere l’handshake, elencare i nove strumenti e fare una chiamata di prova. La guida completa alla GUI (handshake → strumenti → OAuth) è ancora in fase di verifica — trattala come early access e faccelo sapere se un passaggio è sbagliato.

Gli snippet di configurazione per Claude Code, Cursor, VS Code, Windsurf, Codex, n8n, Claude web, ChatGPT e l’MCP Inspector provengono dalla matrice di verifica delle configurazioni client del backend di Samsa. Le piattaforme contrassegnate come early access non sono state esercitate end-to-end al momento della scrittura — se un passaggio è sbagliato, scrivi a support@samsa.ai e lo correggeremo in fretta.

Sicurezza, credits e accesso

Le chiamate agli strumenti MCP sono azioni reali sulla tua organizzazione — spendono credits e creano asset esattamente come l’app e la REST API. Tratta una API key connessa a un client MCP come qualsiasi altro segreto di produzione.

Credits. generate_image, edit_image e generate_video prelevano dal pool di credits condiviso della tua organizzazione alle tariffe dell’app. Le letture sono gratuite. Controlla il saldo in qualsiasi momento con get_credit_balance.
Scope. Ogni strumento richiede uno scope. Una API key o un token OAuth espone solo gli strumenti consentiti dai suoi scope — restringi una chiave esattamente a ciò di cui un’integrazione ha bisogno.
Revoca dell’accesso. Un admin revoca una API key in Settings → API Keys; la revoca è definitiva e ha effetto alla chiamata immediatamente successiva. Per una connessione OAuth, disconnetti il connector nel tuo client (impostazioni dei connector di Claude o ChatGPT); gli access token possono anche essere revocati all’endpoint di revoca OAuth di Samsa. Una credenziale revocata smette di funzionare immediatamente.

Risoluzione dei problemi

Richieste di accesso ripetute o 401

Un 401 è il server che chiede al client di (ri)autenticarsi.

Client OAuth: disconnetti il connector Samsa e riconnettiti per riavviare l’accesso. Se il consenso non si completa mai, potrebbe essere il flusso via browser in early access — faccelo sapere.
Client con API key: verifica che l’header sia esattamente Authorization: Bearer samsa_sk_... e che la chiave sia valida — una chiave mancante, scaduta o revocata restituisce 401 invalid_api_key. In caso di dubbio, crea una nuova chiave in Settings → API Keys.

Per quale organizzazione sto agendo?

Una credenziale agisce sempre per una sola organizzazione. Una API key agisce per l’organizzazione che la possiede — per agire per un’altra org, usa una chiave creata in quell’org. Una connessione OAuth agisce per l’account e l’organizzazione con cui hai effettuato l’accesso — riconnettiti per cambiare. I credits vengono prelevati da, e gli asset appaiono in, quell’organizzazione.

Chiamata a uno strumento rifiutata — credits insufficienti

Se il pool della tua organizzazione non può coprire una generazione, lo strumento di invio restituisce un errore strutturato insufficient_credits prima che qualsiasi job venga eseguito — nulla viene addebitato. Controlla get_credit_balance, poi ricarica o esegui l’upgrade nell’ app Samsa. Le letture sono sempre gratuite.

Rate limit o troppi job

Tre limiti indipendenti possono rallentare una raffica di chiamate:

Rate di richieste per chiave — 60 richieste/minuto; l’eccesso restituisce rate_limited.
Concorrenza per organizzazione — al massimo 5 job in corso alla volta; un sesto restituisce too_many_active_jobs. Lascia finire i job (interroga get_job_status) prima di inviarne altri.
Concorrenza del transport MCP — una raffica di richieste /mcp simultanee su un singolo worker può restituire un transitorio 429 concurrency_limit_exceeded con Retry-After: 1. Aspetta un secondo e riprova.

Consulta Rate limits per il quadro completo e le indicazioni sul back-off.

Uno strumento manca o dice che gli manca uno scope

Gli strumenti che non puoi chiamare sono nascosti o rifiutati perché la credenziale connessa non ha il loro scope. Per esempio, generate_image necessita di images.generate. Modifica gli scope della chiave (o emetti una nuova chiave) in Settings → API Keys, poi riconnettiti.

Vedi anche

Autenticazione

Chiavi di organizzazione, scope e l’header Bearer.

Prezzi

Come vengono calcolati i credits per immagini, modifiche e video.

Rate limits

Rate per chiave, concorrenza per org e back-off.

Riferimento API

La superficie REST dietro gli stessi strumenti.

Per iniziare

API

Verifica dei contenuti

Genera immagini

Magic Edit

Crea video

Traccia job e credits

Connettiti in tre passaggi

Autenticazione

Strumenti

Parametri

Il pattern asincrono

Configura il tuo client

Sicurezza, credits e accesso

Risoluzione dei problemi

Vedi anche

Autenticazione

Prezzi

Rate limits

Riferimento API

Genera immagini

Magic Edit

Crea video

Traccia job e credits

​Connettiti in tre passaggi

​Autenticazione

​Strumenti

​Parametri

​Il pattern asincrono

​Configura il tuo client

​Sicurezza, credits e accesso

​Risoluzione dei problemi

​Vedi anche

Autenticazione

Prezzi

Rate limits

Riferimento API

Connettiti in tre passaggi

Autenticazione

Strumenti

Parametri

Il pattern asincrono

Configura il tuo client

Sicurezza, credits e accesso

Risoluzione dei problemi

Vedi anche