> ## 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 > Verbinde Samsa mit Claude, ChatGPT und jedem MCP client — generiere Bilder mit deinen trainierten Modellen, Magic Edit, Video und Credit-Checks als Tools, über OAuth oder einen API key. Samsa betreibt einen **remote Model Context Protocol (MCP) server**, sodass jeder MCP-fähige Client — Claude, ChatGPT, Claude Code, Cursor, n8n und mehr — das Samsa-Studio deiner Organisation als eine Reihe von Tools steuert. Generiere Bilder mit deinen trainierten **style**-, **object**-, **person**- und **setting**-Modellen, führe **Magic Edit** aus, produziere **Video** und prüfe dein **Credit-Guthaben** — alles aus der App oder dem Agenten heraus, in dem du bereits arbeitest. Nichts zu installieren: nur eine URL und ein Login. Verwandle einen Prompt in Bilder und komponiere dabei optional die trainierten **style**-, **object**-, **person**- und **setting**-Modelle sowie Farbpaletten deiner Organisation. Bearbeite ein bestehendes Bild per Prompt — mit oder ohne Maske — und nutze dieselben trainierten Modelle für markenkonforme Ergebnisse. Produziere Video aus einem Startframe, aus Text oder aus Text, der mit deinen trainierten Modellen gestylt ist — alles als ein einziger Tool-Aufruf. Frage jeden Job bis zum Abschluss ab und lies das verbleibende Credit-Guthaben deiner Organisation — Reads sind immer kostenlos. **Server URL** — füge diesen einen Endpoint zu jedem MCP client hinzu: ``` https://api.samsa.ai/mcp ``` Es ist ein **remote** Server über **Streamable HTTP** — nichts zu installieren, kein lokaler Prozess zum Ausführen, und ein einziger Pfad (`/mcp`, ohne abschließenden Slash) bedient beide Authentifizierungsmodi. Der Transport ist zustandslos: Jeder Tool-Aufruf gibt eine einzelne JSON-Antwort zurück, und Generierungs-Tools liefern sofort eine Job-id, sodass nichts einen langlebigen Stream offen hält. ## In drei Schritten verbunden Interaktive Apps — **Claude** und **ChatGPT** — melden sich mit **OAuth** an; du bestätigst einen Consent-Screen in der Samsa-App und fügst nie einen Key ein. Headless Clients — **Claude Code**, **Cursor**, **n8n**, SDKs — verwenden einen [API key](/de/guides/authentication), der in **Settings → API Keys** erstellt wird. Richte deinen Client auf `https://api.samsa.ai/mcp`. Es gibt nichts zu installieren und keinen lokalen Prozess — siehe [deinen Client unten](#richte-deinen-client-ein) für die genaue einmalige Einrichtung. Dein Client listet die **neun Samsa-Tools**. Bitte ihn, ein Bild zu generieren, einen Magic Edit auszuführen, ein Video zu erstellen oder deine trainierten Modelle zu erstellen und zu aktualisieren — er reicht jeden Job ein und fragt die asynchronen bis zum Abschluss für dich ab. ## Authentifizierung Der MCP-Endpoint akzeptiert **zwei Arten von Zugangsdaten auf derselben URL**. Wähle die, die zu deinem Client passt: | Modus | Am besten für | Wie es funktioniert | | -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth 2.1** | Interaktive Apps — **Claude** (Web/Desktop), **ChatGPT** | Du meldest dich mit deinem Samsa-Konto an und bestätigst einen Consent-Screen in der App. Der Client verwaltet das Token; du fügst nie einen Key ein. | | **API key** (`samsa_sk_…`) | Headless Clients — **Claude Code**, **Cursor**, **VS Code**, **n8n**, SDKs | Sende `Authorization: Bearer samsa_sk_…`. Erstelle Keys in **Settings → API Keys**; die [Scopes](/de/guides/authentication#scopes) des Keys steuern, welche Tools er aufrufen kann. | Beide handeln für eine **Organisation**: Credits werden aus dem Pool dieser Organisation gezogen und generierte Assets erscheinen in der App unter dem verbundenen Konto. Siehe [Authentifizierung](/de/guides/authentication) dazu, wie Keys, Scopes und Organisationen funktionieren. Der OAuth-Login folgt dem Standard-MCP-Flow: Der Client entdeckt Samsas Authorization-Server aus dem `401`-Challenge, registriert sich dynamisch (PKCE, kein Client-Secret) und schickt dich durch einen Consent-Screen, bevor er ein kurzlebiges Access-Token austauscht. Der interaktive Browser-Consent-Flow ist in **Early Access** — wenn ein Login nicht abschließt, sag uns unter [support@samsa.ai](mailto:support@samsa.ai) Bescheid. ## Tools Der Server stellt **neun Tools** bereit. Die vier Reads (`list_models`, `get_model`, `get_job_status`, `get_credit_balance`) und die beiden Modell-Verwaltungs-Tools (`create_model`, `update_model`) sind kostenlos; die drei Generierungs-Tools kosten [Credits](/de/guides/pricing) aus dem Pool deiner Organisation, zu denselben Raten wie App und REST API. | Tool | Was es tut | Scope | Kosten | | -------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------- | | `list_models` | Listet die einsatzbereiten trainierten Modelle deiner Organisation (id, name, category, thumbnail). | `models.read` | Kostenlos | | `get_model` | Vollständige Details zu einem Modell — status, Referenzbilder, Default-Prompt, Trigger-Wörter. | `models.read` | Kostenlos | | `create_model` | Trainiert ein neues Modell aus 1–10 Referenzbildern (async). | `models.write` | Kostenlos | | `update_model` | Aktualisiert Name, Default-Prompt und/oder die stets angewandte Instruction eines Modells. | `models.write` | Kostenlos | | `generate_image` | Generiert Bilder aus einem Prompt und komponiert dabei optional deine trainierten Modelle. | `images.generate` | 5 × outputs × Auflösung | | `edit_image` | Magic Edit — bearbeitet ein Bild per Prompt. | `images.edit` | 5 pro output | | `generate_video` | Generiert Video aus einem Startframe, aus Text oder aus Text, der mit deinen Modellen gestylt ist. | `videos.generate` | 5 / Sekunde × Engine × Auflösung × Audio | | `get_job_status` | Fragt einen eingereichten Bild-, Edit-, Video- oder Modell-Job nach Status und Ergebnissen ab. | Scope des einreichenden Tools | Kostenlos | | `get_credit_balance` | Liest das verbleibende Credit-Guthaben deiner Organisation und den Abrechnungszeitraum. | `usage.read` | Kostenlos | Ein Tool-Aufruf, der wegen eines fehlenden Scopes abgelehnt wird, gibt einen strukturierten Tool-Fehler zurück (keinen Crash) und nennt den benötigten Scope. Keys werden standardmäßig mit allen Scopes erstellt; ein Admin kann einen Key in **Settings → API Keys** einschränken oder erweitern. ### Parameter * `category` *(optional)* — filtert auf eines von `style`, `object`, `person`, `setting`. Gibt die **einsatzbereiten** Modelle deiner Organisation mit `id`, `name`, `category` und einer presigned `thumbnail_url` zurück. Verwende die ids oder Namen als `style_id` / `object_ids` / `person_ids` / `setting_ids` in `generate_image` und `generate_video` — ein Name wird zu einem für dich sichtbaren Modell aufgelöst. * `model_id` *(erforderlich)* — die id des Modells. Gibt vollständige Details zurück: status, Einsatzbereitschaft, presigned URLs der Referenzbilder, den Default-Prompt und Trigger-Wörter. * `name` *(erforderlich)* — der Modellname. * `category` *(erforderlich)* — eines von `style`, `object`, `person`, `setting`. * `images` *(erforderlich)* — 1–10 Referenzbilder. Jedes ist **entweder** eine öffentliche `https`-URL **oder** ein inline base64-Data-URI (`data:image/png;base64,…`) — `image/jpeg`, `image/png` oder `image/webp`, je ≤ 10 MB. * `instruction` *(optional)* — die stets angewandte Guidance des Modells (≤ 8000 Zeichen), die als verbindliche ("MUST FOLLOW") Vorgabe in jede Generierung eingespeist wird, die das Modell komponiert. Siehe [Modelltraining](/de/api-reference/model-training/overview). * `webhook_url` *(optional)* — eine `https`-URL, die einmal benachrichtigt wird, sobald das Training einen finalen Status erreicht. **Async** — gibt sofort `{ id, status: "pending", estimated_credits }` zurück; frage `get_job_status(kind="model", id=…)` ab (das zusätzlich den `models.read` Scope erfordert), bis `completed` oder `failed`, und verwende die Modell-id dann in `generate_image` / `generate_video`. **Kostenlos** — die Modellerstellung zieht keine Credits ab. Presigned Uploads großer Dateien sind REST-only (nicht über MCP verfügbar) — nutze dafür [`POST /models/prepare`](/de/api-reference/model-training/prepare). * `model_id` *(erforderlich)* — das zu aktualisierende Modell. * `name` *(optional)* — ein neuer Modellname. * `default_prompt` *(optional)* — ein neuer Default-Prompt. * `instruction` *(optional)* — die stets angewandte Guidance des Modells (≤ 8000 Zeichen). Sende einen leeren String, um sie zu löschen. Gib **mindestens eines** von `name`, `default_prompt` oder `instruction` an; ausgelassene Felder bleiben unverändert. **Synchron** — gibt sofort das vollständige aktualisierte Modell zurück (gleiche Form wie `get_model`). **Kostenlos.** * `prompt` *(erforderlich)* — der Text-Prompt. * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(optional)* — ids oder Namen trainierter Modelle aus `list_models` zum Komponieren (ein Name wird zu einem für dich sichtbaren Modell aufgelöst). * `color_palette` *(optional)* — eine anzuwendende Farbpalette, angegeben als **Name oder id** (wie bei den Referenzen auf trainierte Modelle). * `num_outputs` (`1`–`4`, Default `1`), `aspect_ratio` (Default `"1:1"`), `resolution` (Default `"1K"`; `1K` / `2K` / `4K`). `aspect_ratio` akzeptiert `1:1` (Default), `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8` und `8:1`. **Async** — gibt sofort `{ id, status: "pending", estimated_credits }` zurück. Kosten: `5 × num_outputs × Auflösung` (`1K` ×1, `2K` ×2, `4K` ×4), abgezogen beim Einreichen. * `prompt` *(erforderlich)* — wie das Bild bearbeitet werden soll. * Genau **eines** von `image_id` (ein Bild in deinem Samsa-Kontext) oder `image_url` (eine öffentliche https-URL). * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(optional)* — ids oder Namen trainierter Modelle aus `list_models`, um sie für markenkonforme Edits wiederzuverwenden (ein Name wird zu einem für dich sichtbaren Modell aufgelöst), gleichauf mit `generate_image`. * `color_palette` *(optional)* — eine anzuwendende Farbpalette, angegeben als **Name oder id**. * `engine` *(optional)* — `nano_banana_pro` (Default), `gemini` oder `kontext`. Die Angabe einer trainierten-Modell-Referenz oder einer Farbpalette erzwingt `nano_banana_pro`. **Async** — gibt `{ id, status: "pending", estimated_credits }` zurück. Kosten: 5 Credits pro output (`nano_banana_pro` skaliert mit der Auflösung: `1K` ×1, `2K` ×2, `4K` ×4), abgezogen beim Einreichen. * `mode` *(erforderlich)* — eines von: * `image_to_video` — animiert einen Startframe. Erfordert genau eines von `image_id` / `image_url`; optional `end_image_url` bei endframe-fähigen Engines; `prompt` optional. * `text_to_video` — erfordert `prompt`. * `text_to_video_styled` — erfordert `prompt` **und** `style_id`; `object_ids` / `person_ids` / `setting_ids` optional, plus eine optionale `color_palette` (Name oder id). * `engine` *(Default `veo_3_1_lite`)*, `duration` *(Default: die kürzeste von der Engine unterstützte Dauer, in Sekunden)*, `aspect_ratio` *(Default `"16:9"`; auch `9:16`, `1:1`)*. **Async** — gibt `{ id, status: "pending", estimated_credits }` zurück. Kosten: `5 / Sekunde × Engine × Auflösung × Audio`-Multiplikatoren; der styled-Modus addiert pauschal 10 für das Zwischenbild. Siehe [Preise](/de/guides/pricing#videogenerierung). * `kind` *(erforderlich)* — `image_generation`, `image_edit`, `video` oder `model`. * `id` *(erforderlich)* — die Job- oder Modell-id, die ein Submit-Tool zurückgegeben hat. Gibt den Status (`pending` → `processing` → `completed` / `failed`) zurück und, sobald `completed`, presigned Ergebnis-URLs, die 24 Stunden gültig sind. Erfordert den Scope des einreichenden Tools (`models.read` für `kind: "model"`). Bei einem abgeschlossenen **Bild**-Job (`image_generation` oder `image_edit`) enthält die Antwort außerdem das Bild selbst als **herunterskalierte Inline-Vorschau** — sodass MCP clients es direkt rendern können — neben dem Link zum Bild in voller Auflösung. Die Vorschau ist eine Kopie mit reduzierter Auflösung für die schnelle Anzeige; rufe den Link ab, um das Original in voller Auflösung zu erhalten. Keine Parameter. Gibt das verfügbare Gesamtguthaben deiner Organisation, die Plan-Credits, die Top-up-Credits und den aktuellen Abrechnungszeitraum zurück. ## Das Async-Muster Die drei Generierungs-Tools sind **asynchron** — sie stellen einen Job in die Warteschlange und kehren sofort zurück, sodass dein Client nie auf ein Rendering warten muss. Rufe `generate_image`, `edit_image` oder `generate_video` auf. Es gibt in Millisekunden `{ id, status: "pending", estimated_credits, next_step }` zurück, und die geschätzten Credits werden beim Einreichen aus dem Pool deiner Organisation abgezogen. Rufe `get_job_status(kind=…, id=…)` mit der id auf, die du erhalten hast. Der Status wechselt `pending` → `processing` → `completed` (oder `failed`). Bild-Jobs sind typischerweise in 30 Sekunden bis zwei Minuten fertig, Video in einer bis fünf. Sobald `completed`, trägt die Antwort presigned Ergebnis-URLs, die 24 Stunden gültig sind. Wenn ein Job auf Samsas Seite `failed` endet, werden die Credits automatisch an denselben Pool [zurückerstattet](/de/guides/pricing#refunds). Der Server teilt das den verbundenen Modellen selbst mit: Jedes Submit-Ergebnis enthält einen `next_step`-String mit dem exakten `get_job_status`-Aufruf, sodass ein fähiger Agent ohne zusätzliches Prompting abfragt. ## Richte deinen Client ein Füge `https://api.samsa.ai/mcp` zu deinem Client unten hinzu. **Claude** und **ChatGPT** melden sich mit OAuth an; jeder andere Client authentifiziert sich mit einem [API key](/de/guides/authentication) (`Authorization: Bearer samsa_sk_…`). Die API-key-Snippets unten zeigen den Key aus Gründen der Lesbarkeit inline. In jeder Konfiguration, die committet oder geteilt wird, **speichere keinen echten Key** — verwende die Interpolation von Umgebungsvariablen deines Clients (gezeigt für Claude Code, Cursor und VS Code) oder halte die Konfiguration auf Benutzerebene. Ein geleakter `samsa_sk_…` sollte sofort [widerrufen](/de/guides/authentication#einen-key-rotieren) werden. **OAuth · Early Access — sag uns Bescheid, wenn das nicht klappt** Claude (Web und Desktop) verbindet sich mit remote MCP servern als **Custom Connector**: Öffne **Settings → Connectors → Add custom connector** und setze die URL auf `https://api.samsa.ai/mcp`. Claude öffnet Samsas **OAuth-Login**; melde dich an und bestätige den Consent-Screen. Claudes Tool-Liste zeigt dann die Samsa-Tools. Die genauen Menü-Beschriftungen variieren je nach Version — das Wesentliche ist der Custom-Connector-Flow und die Samsa-Server-URL. Claude Web ruft `/mcp` aus dem Browser mit `Origin: https://claude.ai` auf, was Samsa erlaubt, sodass Discovery und Login ohne zusätzliche Konfiguration funktionieren. Folge auf dem Desktop Anthropics aktuellen Connector-Anweisungen und verwende dieselbe Server-URL. **OAuth · Early Access — sag uns Bescheid, wenn das nicht klappt** Öffne in ChatGPT **Settings → Apps & Connectors** und aktiviere den **Developer-Modus**. Füge eine App-/MCP-Verbindung mit der URL `https://api.samsa.ai/mcp` hinzu. ChatGPT führt den **OAuth 2.1**-Login und -Consent aus; bestätige ihn, um die Samsa-Tools verfügbar zu machen. Die genauen Menü-Beschriftungen variieren je nach Version — das Wesentliche ist das Aktivieren des Developer-Modus und das Hinzufügen der Samsa-Server-URL. Custom-MCP-Verbindungen erfordern einen ChatGPT-Plan, der Developer-Modus / Connectors umfasst; die Verfügbarkeit ändert sich mit der Zeit, prüfe also deinen Plan, wenn die Option fehlt. ChatGPT ruft `/mcp` mit `Origin: https://chatgpt.com` (oder `https://chat.openai.com`) auf, beide erlaubt Samsa. **API key · verifiziert** Füge den Server mit dem HTTP-Transport und einem Bearer-Header hinzu: ```bash theme={null} claude mcp add --transport http samsa https://api.samsa.ai/mcp \ --header "Authorization: Bearer samsa_sk_..." ``` Standardmäßig registriert das den Server für deine eigene Nutzung (local scope). Um ihn mit deinem Team zu teilen, füge `--scope project` hinzu, und Claude Code schreibt eine projektbezogene `.mcp.json`. Da diese Datei committet wird, halte den Key heraus — Claude Code expandiert Umgebungsvariablen in `headers`: ```json theme={null} { "mcpServers": { "samsa": { "type": "http", "url": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer ${SAMSA_API_KEY}" } } } } ``` Bestätige die Verbindung mit `claude mcp get samsa` — sie sollte **Connected** melden. Lieber OAuth? *(Early Access — sag uns Bescheid, wenn das nicht klappt)* Führe `claude mcp add --transport http samsa https://api.samsa.ai/mcp` **ohne** den Header aus und schließe den OAuth-Login bei der ersten Nutzung ab. Das Header-Setup oben ist der verifizierte Weg; die keylose OAuth-Variante wird noch verifiziert. **API key · Early Access — sag uns Bescheid, wenn das nicht klappt** Füge zu `~/.cursor/mcp.json` (global) oder zur projektbezogenen `.cursor/mcp.json` hinzu. Cursor interpoliert Umgebungsvariablen in `headers`, referenziere den Key also, statt ihn in einer geteilten Datei inline zu setzen: ```json theme={null} { "mcpServers": { "samsa": { "url": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer ${env:SAMSA_API_KEY}" } } } } ``` **API key · Early Access — sag uns Bescheid, wenn das nicht klappt** Füge zu `.vscode/mcp.json` hinzu: ```json theme={null} { "servers": { "samsa": { "type": "http", "url": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer samsa_sk_..." } } } } ``` Committe keinen echten Key in einer Workspace-Datei. VS Code unterstützt `${input:...}`-Variablen und MCP-Konfiguration auf Benutzerebene — verwende eine davon, damit das Secret nicht mit deinem Projekt eingecheckt wird. **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Füge zu `~/.codeium/windsurf/mcp_config.json` hinzu: ```json theme={null} { "mcpServers": { "samsa": { "serverUrl": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer samsa_sk_..." } } } } ``` **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Füge zu `~/.codex/config.toml` hinzu: ```toml theme={null} [mcp_servers.samsa] url = "https://api.samsa.ai/mcp" http_headers = { Authorization = "Bearer samsa_sk_..." } ``` **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Setze im **MCP Client**-Node: * **Endpoint** — `https://api.samsa.ai/mcp` * **Transport** — `HTTP Streamable` * **Authentication** — Header Auth mit `Authorization: Bearer samsa_sk_...` n8n läuft serverseitig (kein Browser-`Origin`-Header), verbindet sich also ohne jede zusätzliche Konfiguration. **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Füge einen HTTP-MCP-server zu `~/.gemini/settings.json` hinzu. Die Namen der Config-Keys unterscheiden sich zwischen Gemini-CLI-Versionen — prüfe sie gegen die aktuelle Gemini-CLI-MCP-Doku — aber die Form ist die Samsa-URL plus ein Bearer-Header: ```json theme={null} { "mcpServers": { "samsa": { "httpUrl": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer samsa_sk_..." } } } } ``` **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Copilot Studio verbindet sich mit MCP servern über einen **Custom Connector / eine MCP-Verbindung**. Erstelle im Maker-Portal eine Custom-MCP-Verbindung, die auf `https://api.samsa.ai/mcp` zeigt, und gib den Header `Authorization: Bearer samsa_sk_...` als Verbindungs-Credential an. Die genaue Formulierung des Portals ändert sich mit der Zeit — folge Microsofts aktueller Anleitung „connect to an MCP server" und verwende die Samsa-URL und den Header oben. **(Early Access — sag uns Bescheid, wenn das nicht klappt)** Um den Server von einem neutralen Tool aus zu verifizieren, verwende den [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Steuere ihn über die GUI (oder eine Config-Datei) mit dem Streamable-HTTP-Transport: ```json theme={null} { "mcpServers": { "samsa": { "type": "streamable-http", "url": "https://api.samsa.ai/mcp", "headers": { "Authorization": "Bearer samsa_sk_..." } } } } ``` Der Inspector verwendet denselben Streamable-HTTP-Transport, gegen den Samsa verifiziert, und läuft auf `http://localhost:6274`, was Samsa erlaubt. Nutze ihn, um den Handshake durchzugehen, die neun Tools zu listen und einen Testaufruf zu machen. Der vollständige GUI-Durchlauf (Handshake → Tools → OAuth) wird noch verifiziert — behandle ihn als Early Access und sag uns Bescheid, wenn ein Schritt daneben liegt. Config-Snippets für Claude Code, Cursor, VS Code, Windsurf, Codex, n8n, Claude Web, ChatGPT und den MCP Inspector stammen aus Samsas Backend-Matrix zur Verifizierung der Client-Konfigurationen. Als **Early Access** markierte Plattformen wurden zum Zeitpunkt der Erstellung nicht end-to-end getestet — wenn ein Schritt daneben liegt, schreib an [support@samsa.ai](mailto:support@samsa.ai), und wir beheben es schnell. ## Sicherheit, Credits & Zugriff MCP-Tool-Aufrufe sind **echte Aktionen auf deiner Organisation** — sie geben Credits aus und erstellen Assets genau wie App und REST API. Behandle einen mit einem MCP client verbundenen API key wie jedes andere Produktions-Secret. * **Credits.** `generate_image`, `edit_image` und `generate_video` ziehen aus dem gemeinsamen [Credit-Pool](/de/guides/pricing) deiner Organisation zu den Raten der App. Reads sind kostenlos. Prüfe das Guthaben jederzeit mit `get_credit_balance`. * **Scopes.** Jedes Tool erfordert einen [Scope](/de/guides/authentication#scopes). Ein API key oder OAuth-Token stellt nur die Tools bereit, die seine Scopes erlauben — schränke einen Key auf genau das ein, was eine Integration braucht. * **Zugriff widerrufen.** Ein Admin widerruft einen API key in **Settings → API Keys**; der Widerruf ist terminal und wird beim allernächsten Aufruf wirksam. Für eine OAuth-Verbindung trenne den Connector in deinem Client (Claude- oder ChatGPT-Connector-Einstellungen); Access-Tokens können auch an Samsas OAuth-Revocation-Endpoint widerrufen werden. Ein widerrufenes Credential funktioniert sofort nicht mehr. ## Fehlerbehebung Ein `401` ist der Server, der den Client bittet, sich (erneut) zu authentifizieren. * **OAuth-Clients:** trenne den Samsa-Connector und verbinde ihn erneut, um den Login neu zu starten. Wenn der Consent nie abschließt, kann es der Early-Access-Browser-Flow sein — sag uns Bescheid. * **API-key-Clients:** bestätige, dass der Header exakt `Authorization: Bearer samsa_sk_...` lautet und der Key gültig ist — ein fehlender, abgelaufener oder widerrufener Key gibt [`401 invalid_api_key`](/de/guides/errors#invalid_api_key) zurück. Erstelle im Zweifel einen frischen Key in **Settings → API Keys**. Ein Credential handelt immer für **eine Organisation**. Ein **API key** handelt für die Organisation, die ihn besitzt — um für eine andere Org zu handeln, verwende einen Key, der in dieser Org erstellt wurde. Eine **OAuth**-Verbindung handelt für das Konto und die Organisation, mit denen du dich angemeldet hast — verbinde dich neu, um zu wechseln. Credits werden aus dieser Organisation gezogen, und Assets erscheinen in ihr. Wenn der Pool deiner Organisation eine Generierung nicht abdecken kann, gibt das Submit-Tool einen strukturierten [`insufficient_credits`](/de/guides/errors#insufficient_credits)-Fehler **zurück, bevor** irgendein Job läuft — es wird nichts berechnet. Prüfe `get_credit_balance`, dann lade auf oder upgrade in der [Samsa-App](https://app.samsa.ai). Reads sind immer kostenlos. Drei unabhängige Limits können einen Ansturm von Aufrufen bremsen: * **Request-Rate pro Key** — 60 Requests/Minute; ein Überschuss gibt [`rate_limited`](/de/guides/errors#rate_limited) zurück. * **Concurrency pro Organisation** — höchstens 5 gleichzeitige Jobs; ein sechster gibt [`too_many_active_jobs`](/de/guides/errors#too_many_active_jobs) zurück. Lass Jobs fertig werden (frage `get_job_status` ab), bevor du weitere einreichst. * **MCP-Transport-Concurrency** — ein Ansturm gleichzeitiger `/mcp`-Requests auf einem einzelnen Worker kann einen transienten `429 concurrency_limit_exceeded` mit `Retry-After: 1` zurückgeben. Warte eine Sekunde und versuche es erneut. Siehe [Rate Limits](/de/guides/rate-limits) für das vollständige Bild und Hinweise zum Back-off. Tools, die du nicht aufrufen kannst, sind versteckt oder abgelehnt, weil dem verbundenen Credential ihr [Scope](/de/guides/authentication#scopes) fehlt. Zum Beispiel braucht `generate_image` `images.generate`. Bearbeite die Scopes des Keys (oder erstelle einen neuen Key) in **Settings → API Keys** und verbinde dich dann neu. ## Siehe auch Organisations-Keys, Scopes und der Bearer-Header. Wie Bild-, Edit- und Video-Credits berechnet werden. Rate pro Key, Concurrency pro Org und Back-off. Die REST-Oberfläche hinter denselben Tools.