MCP server - Samsa API

Samsa runs a remote Model Context Protocol (MCP) server, so any MCP-capable client — Claude, ChatGPT, Claude Code, Cursor, n8n, and more — drives your organization’s Samsa studio as a set of tools. Generate images with your trained style, object, person, and setting models, run Magic Edit, produce video, and check your credit balance — all from inside the app or agent you already work in. Nothing to install: it’s one URL and a sign-in.

Generate images

Turn a prompt into images, optionally composing your organization’s trained style, object, person, and setting models and color palettes.

Magic Edit

Edit an existing image from a prompt — with or without a mask — and reuse the same trained models for on-brand results.

Create video

Produce video from a start frame, from text, or from text styled with your trained models — all as a single tool call.

Track jobs & credits

Poll any job to completion and read your organization’s remaining credit balance — reads are always free.

Server URL — add this one endpoint to any MCP client:

https://api.samsa.ai/mcp

It is a remote server over Streamable HTTP — there is nothing to install, no local process to run, and a single path (/mcp, no trailing slash) serves both authentication modes. The transport is stateless: every tool call returns a single JSON response, and generation tools return a job id immediately so nothing holds a long-lived stream open.

Get connected in three steps

Get your credentials

Interactive apps — Claude and ChatGPT — sign in with OAuth; you approve a consent screen in the Samsa app and never paste a key. Headless clients — Claude Code, Cursor, n8n, SDKs — use an API key created in Settings → API Keys.

Add the server

Point your client at https://api.samsa.ai/mcp. There’s nothing to install and no local process — see your client below for the exact one-time setup.

Start creating

Your client lists the nine Samsa tools. Ask it to generate an image, run a Magic Edit, make a video, or create and update your trained models — it submits each job and polls the async ones to completion for you.

Authentication

The MCP endpoint accepts two credential types on the same URL. Pick the one that matches your client:

Mode	Best for	How it works
OAuth 2.1	Interactive apps — Claude (web/desktop), ChatGPT	You sign in with your Samsa account and approve a consent screen in the app. The client handles the token; you never paste a key.
API key (`samsa_sk_…`)	Headless clients — Claude Code, Cursor, VS Code, n8n, SDKs	Send `Authorization: Bearer samsa_sk_…`. Create keys in Settings → API Keys; the key’s scopes gate which tools it can call.

Both act for an organization: credits are drawn from that organization’s pool and generated assets appear in the app under the connected account. See Authentication for how keys, scopes, and organizations work.

OAuth sign-in follows the standard MCP flow: the client discovers Samsa’s authorization server from the 401 challenge, registers itself dynamically (PKCE, no client secret), and sends you through a consent screen before exchanging a short-lived access token. The interactive browser consent flow is in early access — if a sign-in doesn’t complete, tell us at support@samsa.ai.

Tools

The server exposes nine tools. The four reads (list_models, get_model, get_job_status, get_credit_balance) and the two model-management tools (create_model, update_model) are free; the three generation tools cost credits from your organization’s pool, at the same rates as the app and REST API.

Tool	What it does	Scope	Cost
`list_models`	List your organization’s ready trained models (id, name, category, thumbnail).	`models.read`	Free
`get_model`	Full detail for one model — status, reference images, default prompt, trigger words.	`models.read`	Free
`create_model`	Train a new model from 1–10 reference images (async).	`models.write`	Free
`update_model`	Update a model’s name, default prompt, and/or always-applied instruction.	`models.write`	Free
`generate_image`	Generate images from a prompt, optionally composing your trained models.	`images.generate`	5 × outputs × resolution
`edit_image`	Magic Edit — edit an image from a prompt.	`images.edit`	5 per output
`generate_video`	Generate video from a start frame, from text, or from text styled with your models.	`videos.generate`	5 / second × engine × resolution × audio
`get_job_status`	Poll a submitted image, edit, video, or model job for status and results.	scope of the submitting tool	Free
`get_credit_balance`	Read your organization’s remaining credit balance and billing period.	`usage.read`	Free

A tool call rejected for a missing scope returns a structured tool error (not a crash) naming the scope it needs. Keys are created with all scopes by default; an admin can narrow or widen a key in Settings → API Keys.

Parameters

list_models(category?)

category (optional) — filter to one of style, object, person, setting.

Returns your organization’s ready models with id, name, category, and a presigned thumbnail_url. Use the ids or names as style_id / object_ids / person_ids / setting_ids in generate_image and generate_video — a name resolves to a model visible to you.

get_model(model_id)

model_id (required) — the model’s id.

Returns full detail: status, readiness, presigned reference-image URLs, the default prompt, and trigger words.

create_model(name, category, images, …)

name (required) — the model name.
category (required) — one of style, object, person, setting.
images (required) — 1–10 reference images. Each is either a public https URL or an inline base64 data URI (data:image/png;base64,…) — image/jpeg, image/png, or image/webp, ≤ 10 MB each.
instruction (optional) — the model’s always-applied guidance (≤ 8000 chars), injected as mandatory (“MUST FOLLOW”) direction into every generation that composes the model. See Model Training.
webhook_url (optional) — an https URL notified once when training reaches a terminal status.

Async — returns { id, status: "pending", estimated_credits } immediately; poll get_job_status(kind="model", id=…) (which also needs the models.read scope) until completed or failed, then use the model id in generate_image / generate_video. Free — model creation deducts no credits. Large-file presigned uploads are REST-only (not exposed over MCP) — use POST /models/prepare for those.

update_model(model_id, …)

model_id (required) — the model to update.
name (optional) — a new model name.
default_prompt (optional) — a new default prompt.
instruction (optional) — the model’s always-applied guidance (≤ 8000 chars). Send an empty string to clear it.

Supply at least one of name, default_prompt, or instruction; omitted fields are left unchanged. Synchronous — returns the full updated model immediately (same shape as get_model). Free.

generate_image(prompt, …)

prompt (required) — the text prompt.
style_id, object_ids, person_ids, setting_ids (optional) — trained model ids or names from list_models to compose (a name resolves to a model visible to you).
num_outputs (default 1), aspect_ratio (default "1:1"), resolution (default "1K"; 1K / 2K / 4K).

Async — returns { id, status: "pending", estimated_credits } immediately. Cost: 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4), deducted at submit.

edit_image(prompt, …)

prompt (required) — how to edit the image.
Exactly one of image_id (an image in your Samsa context) or image_url (a public https URL).
engine (optional) — nano_banana_pro (default), gemini, or kontext.

Async — returns { id, status: "pending", estimated_credits }. Cost: 5 credits per output (nano_banana_pro scales with resolution: 1K ×1, 2K ×2, 4K ×4), deducted at submit.

generate_video(mode, …)

mode (required) — one of:
- image_to_video — animate a start frame. Requires exactly one of image_id / image_url; optional end_image_url on end-frame-capable engines; prompt optional.
- text_to_video — requires prompt.
- text_to_video_styled — requires prompt and style_id; object_ids / person_ids / setting_ids optional.
engine (default veo_3_1_lite), duration (default: the engine’s shortest supported duration, in seconds), aspect_ratio (default "16:9"; also 9:16, 1:1).

Async — returns { id, status: "pending", estimated_credits }. Cost: 5 / second × engine × resolution × audio multipliers; styled mode adds a flat 10 for the intermediate image. See pricing.

get_job_status(kind, id)

kind (required) — image_generation, image_edit, video, or model.
id (required) — the job or model id a submit tool returned.

Returns the status (pending → processing → completed / failed) and, once completed, presigned result URLs valid for 24 hours. Requires the scope of the submitting tool (models.read for kind: "model").

get_credit_balance()

No parameters. Returns your organization’s available total, plan credits, top-up credits, and the current billing period.

The async pattern

The three generation tools are asynchronous — they enqueue a job and return right away, so your client never blocks waiting for a render.

Submit

Call generate_image, edit_image, or generate_video. It returns { id, status: "pending", estimated_credits, next_step } in milliseconds, and the estimated credits are deducted from your organization’s pool at submit.

Poll

Call get_job_status(kind=…, id=…) with the id you received. The status moves pending → processing → completed (or failed). Image jobs typically finish in 30 seconds to two minutes; video in one to five.

Collect

Once completed, the response carries presigned result URLs valid for 24 hours. If a job ends failed on Samsa’s side, the credits are automatically refunded to the same pool.

The server tells connected models this itself: every submit result includes a next_step string with the exact get_job_status call to make, so a capable agent polls without extra prompting.

Set up your client

Add https://api.samsa.ai/mcp to your client below. Claude and ChatGPT sign in with OAuth; every other client authenticates with an API key (Authorization: Bearer samsa_sk_…).

The API-key snippets below show the key inline for readability. In any config that is committed or shared, don’t store a real key — use your client’s environment-variable interpolation (shown for Claude Code, Cursor, and VS Code) or keep the config user-level. A leaked samsa_sk_… should be revoked immediately.

OAuth · early access — tell us if this breaksClaude (web and desktop) connects to remote MCP servers as a custom connector:

Add the connector

Open Settings → Connectors → Add custom connector and set the URL to https://api.samsa.ai/mcp.

Claude opens Samsa’s OAuth sign-in; sign in and approve the consent screen. Claude’s tools list then shows the Samsa tools.

Exact menu labels vary by version — the essentials are the custom-connector flow and the Samsa server URL. Claude web calls /mcp from the browser with Origin: https://claude.ai, which Samsa allows, so discovery and sign-in work without extra configuration. On desktop, follow Anthropic’s current connector instructions and use the same server URL.

OAuth · early access — tell us if this breaks

Enable developer mode

In ChatGPT, open Settings → Apps & Connectors and enable developer mode.

Add the connection

Add an app / MCP connection with the URL https://api.samsa.ai/mcp.

ChatGPT runs the OAuth 2.1 sign-in and consent; approve it to expose the Samsa tools.

Exact menu labels vary by version — the essentials are enabling developer mode and adding the Samsa server URL. Custom MCP connections require a ChatGPT plan that includes developer mode / connectors; availability changes over time, so check your plan if the option is missing. ChatGPT calls /mcp with Origin: https://chatgpt.com (or https://chat.openai.com), both of which Samsa allows.

API key · verifiedAdd the server with the HTTP transport and a Bearer header:

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

By default this registers the server for your own use (local scope). To share it with your team, add --scope project and Claude Code writes a project .mcp.json. Because that file is committed, keep the key out of it — Claude Code expands environment variables in headers:

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

Confirm the connection with claude mcp get samsa — it should report Connected.Prefer OAuth? (early access — tell us if this breaks) Run claude mcp add --transport http samsa https://api.samsa.ai/mcp without the header and complete the OAuth sign-in on first use. The header setup above is the verified path; the keyless OAuth variant is still being verified.

API key · early access — tell us if this breaksAdd to ~/.cursor/mcp.json (global) or project .cursor/mcp.json. Cursor interpolates environment variables in headers, so reference the key rather than inlining it in a shared file:

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

API key · early access — tell us if this breaksAdd to .vscode/mcp.json:

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

Don’t commit a real key in a workspace file. VS Code supports ${input:...} variables and user-level MCP config — use one of those so the secret isn’t checked in with your project.

Windsurf · early access

(early access — tell us if this breaks)Add to ~/.codeium/windsurf/mcp_config.json:

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

Codex (OpenAI) · early access

(early access — tell us if this breaks)Add to ~/.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 — tell us if this breaks)In the MCP Client node, set:

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

n8n runs server-side (no browser Origin header), so it connects without any extra configuration.

Gemini CLI · early access

(early access — tell us if this breaks)Add an HTTP MCP server to ~/.gemini/settings.json. Config key names differ across Gemini CLI versions — confirm against the current Gemini CLI MCP docs — but the shape is the Samsa URL plus a Bearer header:

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

Microsoft Copilot Studio · early access

(early access — tell us if this breaks)Copilot Studio connects to MCP servers through a custom connector / MCP connection. In the maker portal, create a custom MCP connection pointing at https://api.samsa.ai/mcp and supply the Authorization: Bearer samsa_sk_... header as the connection credential. The portal’s exact wording changes over time — follow Microsoft’s current “connect to an MCP server” guidance and use the Samsa URL and header above.

Test it — MCP Inspector · early access

(early access — tell us if this breaks)To verify the server from a neutral tool, use the MCP Inspector. Drive it from the GUI (or a config file) with the Streamable-HTTP transport:

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

The Inspector uses the same Streamable-HTTP transport Samsa verifies against, and runs on http://localhost:6274, which Samsa allows. Use it to walk the handshake, list the nine tools, and make a test call. The full GUI walkthrough (handshake → tools → OAuth) is still being verified — treat it as early access and tell us if a step is off.

Config snippets for Claude Code, Cursor, VS Code, Windsurf, Codex, n8n, Claude web, ChatGPT, and the MCP Inspector come from Samsa’s backend client-config verification matrix. Platforms marked early access were not exercised end-to-end at the time of writing — if a step is off, email support@samsa.ai and we’ll fix it fast.

Security, credits & access

MCP tool calls are real actions on your organization — they spend credits and create assets exactly like the app and REST API. Treat an API key connected to an MCP client like any other production secret.

Credits. generate_image, edit_image, and generate_video draw from your organization’s shared credit pool at the app’s rates. Reads are free. Check the balance any time with get_credit_balance.
Scopes. Every tool requires a scope. An API key or OAuth token only exposes the tools its scopes allow — narrow a key to exactly what an integration needs.
Revoking access. An admin revokes an API key in Settings → API Keys; revocation is terminal and takes effect on the very next call. For an OAuth connection, disconnect the connector in your client (Claude or ChatGPT connector settings); access tokens can also be revoked at Samsa’s OAuth revocation endpoint. A revoked credential stops working immediately.

Troubleshooting

A 401 is the server asking the client to (re)authenticate.

OAuth clients: disconnect the Samsa connector and reconnect to restart the sign-in. If consent never completes, it may be the early-access browser flow — tell us.
API-key clients: confirm the header is exactly Authorization: Bearer samsa_sk_... and the key is valid — a missing, expired, or revoked key returns 401 invalid_api_key. Create a fresh key in Settings → API Keys if in doubt.

Which organization am I acting as?

A credential always acts for one organization. An API key acts for the organization that owns it — to act for a different org, use a key created in that org. An OAuth connection acts for the account and organization you signed in with — reconnect to switch. Credits are drawn from, and assets appear in, that organization.

Tool call rejected — insufficient credits

If your organization’s pool can’t cover a generation, the submit tool returns a structured insufficient_credits error before any job runs — nothing is charged. Check get_credit_balance, then top up or upgrade in the Samsa app. Reads are always free.

Rate limited or too many jobs

Three independent limits can slow a burst of calls:

Per-key request rate — 60 requests/minute; excess returns rate_limited.
Per-organization concurrency — at most 5 in-flight jobs at once; a sixth returns too_many_active_jobs. Let jobs finish (poll get_job_status) before submitting more.
MCP transport concurrency — a burst of simultaneous /mcp requests on a single worker can return a transient 429 concurrency_limit_exceeded with Retry-After: 1. Wait one second and retry.

See Rate limits for the full picture and back-off guidance.

A tool is missing or says it lacks a scope

Tools you can’t call are hidden or rejected because the connected credential lacks their scope. For example, generate_image needs images.generate. Edit the key’s scopes (or issue a new key) in Settings → API Keys, then reconnect.

Authentication

Organization keys, scopes, and the Bearer header.

Pricing

How image, edit, and video credits are calculated.

Rate limits

Per-key rate, per-org concurrency, and back-off.

API reference

The REST surface behind the same tools.

Generate images

Magic Edit

Create video

Track jobs & credits

​Get connected in three steps

​Authentication

​Tools

​Parameters

​The async pattern

​Set up your client

​Security, credits & access

​Troubleshooting

​See also

Authentication

Pricing

Rate limits

API reference

Get connected in three steps

Authentication

Tools

Parameters

The async pattern

Set up your client

Security, credits & access

Troubleshooting

See also