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 seven Samsa tools. Ask it to generate an image, run a Magic Edit, or make a video — it submits the job and polls it 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 seven tools. Reads (list_models, get_model, get_job_status, get_credit_balance) 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
`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 as style_id / object_ids / person_ids / setting_ids in generate_image and generate_video.

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.

generate_image(prompt, …)

prompt (required) — the text prompt.
style_id, object_ids, person_ids, setting_ids (optional) — trained model ids from list_models to compose.
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 seven 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

Repeated sign-in prompts or 401s

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