MCP server

Samsa fait tourner un Model Context Protocol (MCP) server distant, pour que n’importe quel client compatible MCP — Claude, ChatGPT, Claude Code, Cursor, n8n et plus encore — pilote le studio Samsa de ton organisation sous forme d’un ensemble d’outils. Génère des images avec tes modèles style, objet, personne et décor entraînés, lance des Magic Edit, produis de la vidéo et vérifie ton solde de credits — le tout depuis l’app ou l’agent dans lequel tu travailles déjà. Rien à installer : une seule URL et une connexion.

Générer des images

Transforme un prompt en images, en composant éventuellement les modèles style, objet, personne et décor entraînés de ton organisation ainsi que des palettes de couleurs.

Magic Edit

Édite une image existante à partir d’un prompt — avec ou sans masque — et réutilise les mêmes modèles entraînés pour des résultats fidèles à ta marque.

Créer de la vidéo

Produis de la vidéo à partir d’une image de départ, à partir de texte, ou à partir de texte stylisé avec tes modèles entraînés — le tout en un seul appel d’outil.

Suivre les jobs & les credits

Interroge n’importe quel job jusqu’à sa complétion et lis le solde de credits restant de ton organisation — les lectures sont toujours gratuites.

URL du server — ajoute ce seul endpoint à n’importe quel client MCP :

https://api.samsa.ai/mcp

C’est un server distant en Streamable HTTP — il n’y a rien à installer, aucun processus local à faire tourner, et un seul chemin (/mcp, sans slash final) sert les deux modes d’authentification. Le transport est stateless : chaque appel d’outil renvoie une unique réponse JSON, et les outils de génération renvoient un id de job immédiatement pour que rien ne maintienne un flux longue durée ouvert.

Se connecter en trois étapes

Récupère tes identifiants

Les apps interactives — Claude et ChatGPT — se connectent avec OAuth ; tu approuves un écran de consentement dans l’app Samsa et ne colles jamais de clé. Les clients headless — Claude Code, Cursor, n8n, les SDKs — utilisent une API key créée dans Settings → API Keys.

Ajoute le server

Pointe ton client vers https://api.samsa.ai/mcp. Il n’y a rien à installer ni de processus local — voir ton client ci-dessous pour la configuration exacte à faire une seule fois.

Commence à créer

Ton client liste les neuf outils Samsa. Demande-lui de générer une image, de lancer un Magic Edit, de faire une vidéo, ou de créer et mettre à jour tes modèles entraînés — il soumet chaque job et interroge les jobs asynchrones jusqu’à leur complétion pour toi.

Authentification

Le endpoint MCP accepte deux types d’identifiants sur la même URL. Choisis celui qui correspond à ton client :

Mode	Idéal pour	Comment ça marche
OAuth 2.1	Apps interactives — Claude (web/desktop), ChatGPT	Tu te connectes avec ton compte Samsa et approuves un écran de consentement dans l’app. Le client gère le token ; tu ne colles jamais de clé.
API key (`samsa_sk_…`)	Clients headless — Claude Code, Cursor, VS Code, n8n, les SDKs	Envoie `Authorization: Bearer samsa_sk_…`. Crée des clés dans Settings → API Keys ; les scopes de la clé déterminent quels outils elle peut appeler.

Les deux agissent pour une organisation : les credits sont prélevés sur le pool de cette organisation et les assets générés apparaissent dans l’app sous le compte connecté. Voir Authentification pour comprendre comment fonctionnent les clés, les scopes et les organisations.

La connexion OAuth suit le flux MCP standard : le client découvre le serveur d’autorisation de Samsa à partir du challenge 401, s’enregistre dynamiquement (PKCE, sans client secret), et te fait passer par un écran de consentement avant d’échanger un access token de courte durée. Le flux de consentement navigateur interactif est en early access — si une connexion ne se termine pas, dis-le-nous à support@samsa.ai.

Outils

Le server expose neuf outils. Les quatre lectures (list_models, get_model, get_job_status, get_credit_balance) et les deux outils de gestion de modèles (create_model, update_model) sont gratuits ; les trois outils de génération coûtent des credits du pool de ton organisation, aux mêmes tarifs que l’app et l’API REST.

Outil	Ce qu’il fait	Scope	Coût
`list_models`	Liste les modèles entraînés prêts de ton organisation (id, nom, catégorie, thumbnail).	`models.read`	Gratuit
`get_model`	Détail complet d’un modèle — statut, images de référence, prompt par défaut, mots déclencheurs.	`models.read`	Gratuit
`create_model`	Entraîne un nouveau modèle à partir de 1–10 images de référence (async).	`models.write`	Gratuit
`update_model`	Met à jour le nom, le prompt par défaut et/ou l’instruction toujours appliquée d’un modèle.	`models.write`	Gratuit
`generate_image`	Génère des images à partir d’un prompt, en composant éventuellement tes modèles entraînés.	`images.generate`	5 × outputs × résolution
`edit_image`	Magic Edit — édite une image à partir d’un prompt.	`images.edit`	5 par output
`generate_video`	Génère de la vidéo à partir d’une image de départ, à partir de texte, ou à partir de texte stylisé avec tes modèles.	`videos.generate`	5 / seconde × moteur × résolution × audio
`get_job_status`	Interroge un job d’image, d’édition, de vidéo ou de modèle soumis pour son statut et ses résultats.	scope de l’outil de soumission	Gratuit
`get_credit_balance`	Lit le solde de credits restant de ton organisation et sa période de facturation.	`usage.read`	Gratuit

Un appel d’outil rejeté pour un scope manquant renvoie une erreur d’outil structurée (pas un crash) nommant le scope dont il a besoin. Les clés sont créées avec tous les scopes par défaut ; un admin peut restreindre ou élargir une clé dans Settings → API Keys.

Paramètres

list_models(category?)

category (optionnel) — filtre sur l’un de style, object, person, setting.

Renvoie les modèles prêts de ton organisation avec id, name, category et une thumbnail_url presignée. Utilise les ids ou les noms comme style_id / object_ids / person_ids / setting_ids dans generate_image et generate_video — un nom est résolu vers un modèle visible pour toi.

get_model(model_id)

model_id (requis) — l’id du modèle.

Renvoie le détail complet : statut, disponibilité, URLs presignées des images de référence, le prompt par défaut et les mots déclencheurs.

create_model(name, category, images, …)

name (requis) — le nom du modèle.
category (requis) — l’un de style, object, person, setting.
images (requis) — 1–10 images de référence. Chacune est soit une URL https publique soit un data URI base64 inline (data:image/png;base64,…) — image/jpeg, image/png ou image/webp, ≤ 10 Mo chacune.
instruction (optionnel) — la guidance toujours appliquée du modèle (≤ 8000 caractères), injectée comme directive obligatoire (“MUST FOLLOW”) dans chaque génération qui compose le modèle. Voir Entraînement de modèles.
webhook_url (optionnel) — une URL https notifiée une fois lorsque l’entraînement atteint un statut terminal.

Async — renvoie { id, status: "pending", estimated_credits } immédiatement ; interroge get_job_status(kind="model", id=…) (qui nécessite aussi le scope models.read) jusqu’à completed ou failed, puis utilise l’id du modèle dans generate_image / generate_video. Gratuit — la création de modèle ne déduit aucun credit. Les uploads presignés de gros fichiers sont réservés au REST (non exposés via MCP) — utilise POST /models/prepare pour cela.

update_model(model_id, …)

model_id (requis) — le modèle à mettre à jour.
name (optionnel) — un nouveau nom de modèle.
default_prompt (optionnel) — un nouveau prompt par défaut.
instruction (optionnel) — la guidance toujours appliquée du modèle (≤ 8000 caractères). Envoie une chaîne vide pour l’effacer.

Fournis au moins un de name, default_prompt ou instruction ; les champs omis restent inchangés. Synchrone — renvoie immédiatement le modèle mis à jour complet (même forme que get_model). Gratuit.

generate_image(prompt, …)

prompt (requis) — le prompt texte.
style_id, object_ids, person_ids, setting_ids (optionnels) — ids ou noms de modèles entraînés issus de list_models à composer (un nom est résolu vers un modèle visible pour toi).
color_palette (optionnel) — une palette de couleurs à appliquer, donnée par son nom ou son id (comme les références de modèles entraînés).
num_outputs (1–4, par défaut 1), aspect_ratio (par défaut "1:1"), resolution (par défaut "1K" ; 1K / 2K / 4K).

aspect_ratio accepte 1:1 (par défaut), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 et 8:1.Async — renvoie { id, status: "pending", estimated_credits } immédiatement. Coût : 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4), déduit à la soumission.

edit_image(prompt, …)

prompt (requis) — comment éditer l’image.
Exactement un de image_id (une image de ton contexte Samsa) ou image_url (une URL https publique).
style_id, object_ids, person_ids, setting_ids (optionnels) — ids ou noms de modèles entraînés issus de list_models à réutiliser pour des éditions fidèles à ta marque (un nom est résolu vers un modèle visible pour toi), à parité avec generate_image.
color_palette (optionnel) — une palette de couleurs à appliquer, donnée par son nom ou son id.
engine (optionnel) — nano_banana_pro (par défaut), gemini ou kontext. Fournir une référence de modèle entraîné ou une palette de couleurs force nano_banana_pro.

Async — renvoie { id, status: "pending", estimated_credits }. Coût : 5 credits par output (nano_banana_pro est mis à l’échelle selon la résolution : 1K ×1, 2K ×2, 4K ×4), déduit à la soumission.

generate_video(mode, …)

mode (requis) — l’un de :
- image_to_video — anime une image de départ. Requiert exactement un de image_id / image_url ; end_image_url optionnel sur les moteurs prenant en charge une image de fin ; prompt optionnel.
- text_to_video — requiert prompt.
- text_to_video_styled — requiert prompt et style_id ; object_ids / person_ids / setting_ids optionnels, plus une color_palette optionnelle (nom ou id).
engine (par défaut veo_3_1_lite), duration (par défaut : la durée la plus courte prise en charge par le moteur, en secondes), aspect_ratio (par défaut "16:9" ; aussi 9:16, 1:1).

Async — renvoie { id, status: "pending", estimated_credits }. Coût : multiplicateurs 5 / seconde × moteur × résolution × audio ; le mode stylisé ajoute un forfait de 10 pour l’image intermédiaire. Voir tarification.

get_job_status(kind, id)

kind (requis) — image_generation, image_edit, video ou model.
id (requis) — l’id de job ou de modèle qu’un outil de soumission a renvoyé.

Renvoie le statut (pending → processing → completed / failed) et, une fois completed, les URLs de résultat presignées valables 24 heures. Requiert le scope de l’outil de soumission (models.read pour kind: "model").Pour un job d’image terminé (image_generation ou image_edit), la réponse inclut aussi l’image elle-même sous forme d’aperçu inline réduit — pour que les clients MCP puissent l’afficher directement — en plus du lien vers l’image en pleine résolution. L’aperçu est une copie en résolution réduite pour un affichage rapide ; récupère le lien pour l’asset original en pleine résolution.

get_credit_balance()

Aucun paramètre. Renvoie le total disponible de ton organisation, les credits du plan, les credits de top-up et la période de facturation actuelle.

Le modèle asynchrone

Les trois outils de génération sont asynchrones — ils mettent un job en file et renvoient immédiatement, pour que ton client ne bloque jamais en attendant un rendu.

Soumettre

Appelle generate_image, edit_image ou generate_video. Il renvoie { id, status: "pending", estimated_credits, next_step } en quelques millisecondes, et les credits estimés sont déduits du pool de ton organisation à la soumission.

Interroger

Appelle get_job_status(kind=…, id=…) avec l’id que tu as reçu. Le statut passe de pending → processing → completed (ou failed). Les jobs d’image finissent généralement en 30 secondes à deux minutes ; la vidéo en une à cinq.

Récupérer

Une fois completed, la réponse porte les URLs de résultat presignées valables 24 heures. Si un job se termine en failed du côté de Samsa, les credits sont automatiquement remboursés sur le même pool.

Le server le dit lui-même aux modèles connectés : chaque résultat de soumission inclut une chaîne next_step avec l’appel exact de get_job_status à effectuer, pour qu’un agent capable interroge sans prompting supplémentaire.

Configure ton client

Ajoute https://api.samsa.ai/mcp à ton client ci-dessous. Claude et ChatGPT se connectent avec OAuth ; tous les autres clients s’authentifient avec une API key (Authorization: Bearer samsa_sk_…).

Les snippets avec API key ci-dessous montrent la clé en clair pour la lisibilité. Dans toute config commitée ou partagée, ne stocke pas de vraie clé — utilise l’interpolation de variables d’environnement de ton client (montrée pour Claude Code, Cursor et VS Code) ou garde la config au niveau utilisateur. Une clé samsa_sk_… divulguée doit être révoquée immédiatement.

OAuth · early access — dis-nous si ça casseClaude (web et desktop) se connecte aux MCP servers distants comme un connecteur personnalisé :

Ajoute le connecteur

Ouvre Settings → Connectors → Add custom connector et définis l’URL sur https://api.samsa.ai/mcp.

Connecte-toi

Claude ouvre la connexion OAuth de Samsa ; connecte-toi et approuve l’écran de consentement. La liste d’outils de Claude affiche alors les outils Samsa.

Les libellés de menu exacts varient selon la version — l’essentiel est le flux de connecteur personnalisé et l’URL du server Samsa. Claude web appelle /mcp depuis le navigateur avec Origin: https://claude.ai, ce que Samsa autorise, donc la découverte et la connexion fonctionnent sans configuration supplémentaire. Sur desktop, suis les instructions de connecteur actuelles d’Anthropic et utilise la même URL de server.

OAuth · early access — dis-nous si ça casse

Active le mode développeur

Dans ChatGPT, ouvre Settings → Apps & Connectors et active le mode développeur.

Ajoute la connexion

Ajoute une connexion app / MCP avec l’URL https://api.samsa.ai/mcp.

Connecte-toi

ChatGPT exécute la connexion et le consentement OAuth 2.1 ; approuve-le pour exposer les outils Samsa.

Les libellés de menu exacts varient selon la version — l’essentiel est d’activer le mode développeur et d’ajouter l’URL du server Samsa. Les connexions MCP personnalisées requièrent un plan ChatGPT incluant le mode développeur / les connecteurs ; la disponibilité change au fil du temps, donc vérifie ton plan si l’option est absente. ChatGPT appelle /mcp avec Origin: https://chatgpt.com (ou https://chat.openai.com), que Samsa autorise tous deux.

API key · vérifiéAjoute le server avec le transport HTTP et un header Bearer :

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

Par défaut, cela enregistre le server pour ton usage personnel (scope local). Pour le partager avec ton équipe, ajoute --scope project et Claude Code écrit un .mcp.json de projet. Comme ce fichier est commité, garde la clé en dehors — Claude Code développe les variables d’environnement dans headers :

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

Confirme la connexion avec claude mcp get samsa — il devrait indiquer Connected.Tu préfères OAuth ? (early access — dis-nous si ça casse) Exécute claude mcp add --transport http samsa https://api.samsa.ai/mcp sans le header et termine la connexion OAuth à la première utilisation. La configuration avec header ci-dessus est le chemin vérifié ; la variante OAuth sans clé est encore en cours de vérification.

API key · early access — dis-nous si ça casseAjoute à ~/.cursor/mcp.json (global) ou au .cursor/mcp.json de projet. Cursor interpole les variables d’environnement dans headers, donc référence la clé plutôt que de l’inliner dans un fichier partagé :

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

API key · early access — dis-nous si ça casseAjoute à .vscode/mcp.json :

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

Ne commite pas de vraie clé dans un fichier de workspace. VS Code prend en charge les variables ${input:...} et la config MCP au niveau utilisateur — utilise l’une d’elles pour que le secret ne soit pas embarqué avec ton projet.

Windsurf · early access

(early access — dis-nous si ça casse)Ajoute à ~/.codeium/windsurf/mcp_config.json :

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

Codex (OpenAI) · early access

(early access — dis-nous si ça casse)Ajoute à ~/.codex/config.toml :

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

n8n — nœud MCP Client · early access

(early access — dis-nous si ça casse)Dans le nœud MCP Client, définis :

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

n8n tourne côté serveur (pas de header Origin de navigateur), donc il se connecte sans configuration supplémentaire.

Gemini CLI · early access

(early access — dis-nous si ça casse)Ajoute un MCP server HTTP à ~/.gemini/settings.json. Les noms de clés de config diffèrent selon les versions de Gemini CLI — vérifie contre la doc MCP actuelle de Gemini CLI — mais la forme est l’URL Samsa plus un header Bearer :

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

Microsoft Copilot Studio · early access

(early access — dis-nous si ça casse)Copilot Studio se connecte aux MCP servers via un connecteur personnalisé / une connexion MCP. Dans le maker portal, crée une connexion MCP personnalisée pointant vers https://api.samsa.ai/mcp et fournis le header Authorization: Bearer samsa_sk_... comme identifiant de connexion. La formulation exacte du portail change au fil du temps — suis les recommandations « connect to an MCP server » actuelles de Microsoft et utilise l’URL et le header Samsa ci-dessus.

Teste-le — MCP Inspector · early access

(early access — dis-nous si ça casse)Pour vérifier le server depuis un outil neutre, utilise le MCP Inspector. Pilote-le depuis la GUI (ou un fichier de config) avec le transport Streamable-HTTP :

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

L’Inspector utilise le même transport Streamable-HTTP contre lequel Samsa est vérifié, et tourne sur http://localhost:6274, que Samsa autorise. Utilise-le pour parcourir le handshake, lister les neuf outils et faire un appel de test. Le parcours GUI complet (handshake → outils → OAuth) est encore en cours de vérification — traite-le comme de l’early access et dis-nous si une étape ne va pas.

Les snippets de config pour Claude Code, Cursor, VS Code, Windsurf, Codex, n8n, Claude web, ChatGPT et le MCP Inspector proviennent de la matrice de vérification de config client du backend de Samsa. Les plateformes marquées early access n’ont pas été exercées de bout en bout au moment de la rédaction — si une étape ne va pas, écris à support@samsa.ai et nous corrigerons vite.

Sécurité, credits & accès

Les appels d’outils MCP sont des actions réelles sur ton organisation — ils dépensent des credits et créent des assets exactement comme l’app et l’API REST. Traite une API key connectée à un client MCP comme n’importe quel autre secret de production.

Credits. generate_image, edit_image et generate_video puisent dans le pool de credits partagé de ton organisation aux tarifs de l’app. Les lectures sont gratuites. Vérifie le solde à tout moment avec get_credit_balance.
Scopes. Chaque outil requiert un scope. Une API key ou un token OAuth n’expose que les outils autorisés par ses scopes — restreins une clé exactement à ce dont une intégration a besoin.
Révoquer l’accès. Un admin révoque une API key dans Settings → API Keys ; la révocation est définitive et prend effet dès l’appel suivant. Pour une connexion OAuth, déconnecte le connecteur dans ton client (paramètres de connecteur de Claude ou ChatGPT) ; les access tokens peuvent aussi être révoqués au endpoint de révocation OAuth de Samsa. Un identifiant révoqué cesse de fonctionner immédiatement.

Dépannage

Invites de connexion répétées ou 401

Un 401 est le server qui demande au client de (re)s’authentifier.

Clients OAuth : déconnecte le connecteur Samsa et reconnecte-toi pour relancer la connexion. Si le consentement ne se termine jamais, c’est peut-être le flux navigateur early-access — dis-le-nous.
Clients API key : confirme que le header est exactement Authorization: Bearer samsa_sk_... et que la clé est valide — une clé manquante, expirée ou révoquée renvoie 401 invalid_api_key. Crée une clé fraîche dans Settings → API Keys en cas de doute.

Pour quelle organisation j'agis ?

Un identifiant agit toujours pour une organisation. Une API key agit pour l’organisation qui la possède — pour agir pour une autre org, utilise une clé créée dans cette org. Une connexion OAuth agit pour le compte et l’organisation avec lesquels tu t’es connecté — reconnecte-toi pour changer. Les credits sont prélevés sur cette organisation, et les assets y apparaissent.

Appel d'outil rejeté — credits insuffisants

Si le pool de ton organisation ne peut pas couvrir une génération, l’outil de soumission renvoie une erreur insufficient_credits structurée avant qu’aucun job ne tourne — rien n’est facturé. Vérifie get_credit_balance, puis recharge ou fais évoluer ton plan dans l’ app Samsa. Les lectures sont toujours gratuites.

Rate limited ou trop de jobs

Trois limites indépendantes peuvent ralentir un burst d’appels :

Rate de requêtes par clé — 60 requêtes/minute ; l’excès renvoie rate_limited.
Concurrence par organisation — au plus 5 jobs en cours à la fois ; un sixième renvoie too_many_active_jobs. Laisse les jobs finir (interroge get_job_status) avant d’en soumettre d’autres.
Concurrence du transport MCP — un burst de requêtes /mcp simultanées sur un même worker peut renvoyer un 429 concurrency_limit_exceeded transitoire avec Retry-After: 1. Attends une seconde et réessaie.

Voir Rate limits pour le tableau complet et les conseils de back-off.

Un outil est absent ou dit qu'il lui manque un scope

Les outils que tu ne peux pas appeler sont masqués ou rejetés parce que l’identifiant connecté n’a pas leur scope. Par exemple, generate_image a besoin de images.generate. Modifie les scopes de la clé (ou émets une nouvelle clé) dans Settings → API Keys, puis reconnecte-toi.

Voir aussi

Authentification

Clés d’organisation, scopes et le header Bearer.

Tarification

Comment les credits d’image, d’édition et de vidéo sont calculés.

Rate limits

Rate par clé, concurrence par org et back-off.

Référence API

La surface REST derrière les mêmes outils.

Prise en main

APIs

Vérification de contenu

Générer des images

Magic Edit

Créer de la vidéo

Suivre les jobs & les credits

Se connecter en trois étapes

Authentification

Outils

Paramètres

Le modèle asynchrone

Configure ton client

Sécurité, credits & accès

Dépannage

Voir aussi

Authentification

Tarification

Rate limits

Référence API

Générer des images

Magic Edit

Créer de la vidéo

Suivre les jobs & les credits

​Se connecter en trois étapes

​Authentification

​Outils

​Paramètres

​Le modèle asynchrone

​Configure ton client

​Sécurité, credits & accès

​Dépannage

​Voir aussi

Authentification

Tarification

Rate limits

Référence API

Se connecter en trois étapes

Authentification

Outils

Paramètres

Le modèle asynchrone

Configure ton client

Sécurité, credits & accès

Dépannage

Voir aussi