> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Samsa to Claude, ChatGPT, and any MCP client — generate images with your trained models, Magic Edit, video, and credit checks as tools, over OAuth or an API key.

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.

<CardGroup cols={2}>
  <Card title="Generate images" icon="image">
    Turn a prompt into images, optionally composing your organization's trained
    **style**, **object**, **person**, and **setting** models and color palettes.
  </Card>

  <Card title="Magic Edit" icon="wand-magic-sparkles">
    Edit an existing image from a prompt — with or without a mask — and reuse the
    same trained models for on-brand results.
  </Card>

  <Card title="Create video" icon="clapperboard">
    Produce video from a start frame, from text, or from text styled with your
    trained models — all as a single tool call.
  </Card>

  <Card title="Track jobs & credits" icon="gauge-high">
    Poll any job to completion and read your organization's remaining credit
    balance — reads are always free.
  </Card>
</CardGroup>

<Info>
  **Server URL** — add this one endpoint to any MCP client:

  ```
  https://api.samsa.ai/mcp
  ```
</Info>

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

<Steps>
  <Step title="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](/guides/authentication) created in **Settings → API Keys**.
  </Step>

  <Step title="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](#set-up-your-client) for the
    exact one-time setup.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/guides/authentication#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](/guides/authentication) for how keys, scopes, and organizations
work.

<Note>
  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](mailto:support@samsa.ai).
</Note>

## 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](/guides/pricing) 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                                     |

<Note>
  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**.
</Note>

### Parameters

<AccordionGroup>
  <Accordion title="list_models(category?)" icon="layer-group">
    * `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`.
  </Accordion>

  <Accordion title="get_model(model_id)" icon="circle-info">
    * `model_id` *(required)* — the model's id.

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

  <Accordion title="generate_image(prompt, …)" icon="image">
    * `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.
  </Accordion>

  <Accordion title="edit_image(prompt, …)" icon="wand-magic-sparkles">
    * `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.
  </Accordion>

  <Accordion title="generate_video(mode, …)" icon="clapperboard">
    * `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](/guides/pricing#video-generation).
  </Accordion>

  <Accordion title="get_job_status(kind, id)" icon="magnifying-glass">
    * `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"`).
  </Accordion>

  <Accordion title="get_credit_balance()" icon="coins">
    No parameters. Returns your organization's available total, plan credits,
    top-up credits, and the current billing period.
  </Accordion>
</AccordionGroup>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/guides/pricing#refunds) to the same pool.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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](/guides/authentication) (`Authorization: Bearer samsa_sk_…`).

<Warning>
  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](/guides/authentication#rotating-a-key) immediately.
</Warning>

<Tabs>
  <Tab title="Claude">
    **OAuth · early access — tell us if this breaks**

    Claude (web and desktop) connects to remote MCP servers as a **custom
    connector**:

    <Steps>
      <Step title="Add the connector">
        Open **Settings → Connectors → Add custom connector** and set the URL to
        `https://api.samsa.ai/mcp`.
      </Step>

      <Step title="Sign in">
        Claude opens Samsa's **OAuth sign-in**; sign in and approve the consent
        screen. Claude's tools list then shows the Samsa tools.
      </Step>
    </Steps>

    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.
  </Tab>

  <Tab title="ChatGPT">
    **OAuth · early access — tell us if this breaks**

    <Steps>
      <Step title="Enable developer mode">
        In ChatGPT, open **Settings → Apps & Connectors** and enable **developer
        mode**.
      </Step>

      <Step title="Add the connection">
        Add an app / MCP connection with the URL `https://api.samsa.ai/mcp`.
      </Step>

      <Step title="Sign in">
        ChatGPT runs the **OAuth 2.1** sign-in and consent; approve it to expose
        the Samsa tools.
      </Step>
    </Steps>

    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.
  </Tab>

  <Tab title="Claude Code">
    **API key · verified**

    Add the server with the HTTP transport and a Bearer header:

    ```bash theme={null}
    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`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    **API key · early access — tell us if this breaks**

    Add 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:

    ```json theme={null}
    {
      "mcpServers": {
        "samsa": {
          "url": "https://api.samsa.ai/mcp",
          "headers": { "Authorization": "Bearer ${env:SAMSA_API_KEY}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    **API key · early access — tell us if this breaks**

    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="More clients">
    <AccordionGroup>
      <Accordion title="Windsurf · early access" icon="wind">
        **(early access — tell us if this breaks)**

        Add to `~/.codeium/windsurf/mcp_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "samsa": {
              "serverUrl": "https://api.samsa.ai/mcp",
              "headers": { "Authorization": "Bearer samsa_sk_..." }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Codex (OpenAI) · early access" icon="code-branch">
        **(early access — tell us if this breaks)**

        Add to `~/.codex/config.toml`:

        ```toml theme={null}
        [mcp_servers.samsa]
        url = "https://api.samsa.ai/mcp"
        http_headers = { Authorization = "Bearer samsa_sk_..." }
        ```
      </Accordion>

      <Accordion title="n8n — MCP Client node · early access" icon="diagram-project">
        **(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.
      </Accordion>

      <Accordion title="Gemini CLI · early access" icon="gem">
        **(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:

        ```json theme={null}
        {
          "mcpServers": {
            "samsa": {
              "httpUrl": "https://api.samsa.ai/mcp",
              "headers": { "Authorization": "Bearer samsa_sk_..." }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Microsoft Copilot Studio · early access" icon="microsoft">
        **(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.
      </Accordion>

      <Accordion title="Test it — MCP Inspector · early access" icon="magnifying-glass">
        **(early access — tell us if this breaks)**

        To verify the server from a neutral tool, use the
        [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Drive
        it from the GUI (or a config file) with the Streamable-HTTP transport:

        ```json theme={null}
        {
          "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.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

<Note>
  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](mailto:support@samsa.ai) and we'll fix it fast.
</Note>

## Security, credits & access

<Warning>
  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.
</Warning>

* **Credits.** `generate_image`, `edit_image`, and `generate_video` draw from your
  organization's shared [credit pool](/guides/pricing) at the app's rates. Reads
  are free. Check the balance any time with `get_credit_balance`.
* **Scopes.** Every tool requires a [scope](/guides/authentication#scopes). 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

<AccordionGroup>
  <Accordion title="Repeated sign-in prompts or 401s" icon="triangle-exclamation">
    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`](/guides/errors#invalid_api_key). Create a
      fresh key in **Settings → API Keys** if in doubt.
  </Accordion>

  <Accordion title="Which organization am I acting as?" icon="building">
    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.
  </Accordion>

  <Accordion title="Tool call rejected — insufficient credits" icon="coins">
    If your organization's pool can't cover a generation, the submit tool returns a
    structured [`insufficient_credits`](/guides/errors#insufficient_credits) error
    **before** any job runs — nothing is charged. Check
    `get_credit_balance`, then top up or upgrade in the
    [Samsa app](https://app.samsa.ai). Reads are always free.
  </Accordion>

  <Accordion title="Rate limited or too many jobs" icon="gauge-high">
    Three independent limits can slow a burst of calls:

    * **Per-key request rate** — 60 requests/minute; excess returns
      [`rate_limited`](/guides/errors#rate_limited).
    * **Per-organization concurrency** — at most 5 in-flight jobs at once; a sixth
      returns [`too_many_active_jobs`](/guides/errors#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](/guides/rate-limits) for the full picture and back-off
    guidance.
  </Accordion>

  <Accordion title="A tool is missing or says it lacks a scope" icon="lock">
    Tools you can't call are hidden or rejected because the connected credential
    lacks their [scope](/guides/authentication#scopes). For example,
    `generate_image` needs `images.generate`. Edit the key's scopes (or issue a new
    key) in **Settings → API Keys**, then reconnect.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    Organization keys, scopes, and the Bearer header.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/guides/pricing">
    How image, edit, and video credits are calculated.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/guides/rate-limits">
    Per-key rate, per-org concurrency, and back-off.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference/introduction">
    The REST surface behind the same tools.
  </Card>
</CardGroup>