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

# Client verbinden

> Einmalige Einrichtung für Claude, ChatGPT, Microsoft Copilot, Cursor, VS Code, n8n und mehr.

Füge `https://api.samsa.ai/mcp` zu deinem Client unten hinzu. **Claude**,
**ChatGPT** und **Microsoft Copilot** können sich mit OAuth anmelden; die übrigen
Clients authentifizieren sich mit einem [API key](/de/guides/authentication)
(`Authorization: Bearer samsa_sk_…`).

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

<Tabs>
  <Tab title="Claude">
    Claude (Web und Desktop) verbindet sich mit remote MCP servern als **Custom
    Connector**:

    <Steps>
      <Step title="Füge den Connector hinzu">
        Öffne **Settings → Connectors → Add custom connector** und setze die URL
        auf `https://api.samsa.ai/mcp`.
      </Step>

      <Step title="Melde dich an">
        Claude öffnet Samsas **OAuth-Login**; melde dich an und bestätige den
        Consent-Screen. Claudes Tool-Liste zeigt dann die Samsa-Tools.
      </Step>
    </Steps>

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

  <Tab title="ChatGPT">
    <Steps>
      <Step title="Aktiviere den Developer-Modus">
        Öffne in ChatGPT **Settings → Apps & Connectors** und aktiviere den
        **Developer-Modus**.
      </Step>

      <Step title="Füge die Verbindung hinzu">
        Füge eine App-/MCP-Verbindung mit der URL `https://api.samsa.ai/mcp` hinzu.
      </Step>

      <Step title="Melde dich an">
        ChatGPT führt den **OAuth 2.1**-Login und -Consent aus; bestätige ihn, um
        die Samsa-Tools verfügbar zu machen.
      </Step>
    </Steps>

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

  <Tab title="Microsoft Copilot">
    Microsoft verbindet MCP server über **Copilot Studio**. Füge Samsa dort einmal
    hinzu und veröffentliche den Agent dann im Kanal **Microsoft 365 Copilot und
    Teams**, damit deine Organisation ihn aus Copilot Chat und Teams nutzt.

    <Steps>
      <Step title="Server hinzufügen">
        Wähle auf der Seite **Tools** deines Agents **Tool hinzufügen → Neues Tool
        → Model Context Protocol**. Setze **Server-URL** auf
        `https://api.samsa.ai/mcp` und gib dem Server Namen und Beschreibung.

        Der Orchestrator des Agents liest diese Beschreibung, um zu entscheiden,
        wann er Samsa aufruft — sei also konkret, etwa „Erzeugt und bearbeitet
        Bilder und Video mit den trainierten Samsa-Modellen der Organisation."
      </Step>

      <Step title="Authentifizierung wählen">
        Samsa funktioniert mit beiden Optionen des Assistenten:

        * **OAuth 2.0 → Dynamic discovery** — Samsa unterstützt Dynamic Client
          Registration mit Discovery, sodass Copilot Studio die Endpoints findet
          und sich selbst registriert. Jede Person meldet sich mit dem eigenen
          Samsa-Konto an, es wird kein Key geteilt.
        * **API key** — setze **Typ** auf **Header** und den Header-Namen auf
          `Authorization`. Der Wert der Verbindung ist `Bearer samsa_sk_…`.
      </Step>

      <Step title="Verbindung erstellen">
        Wähle **Erstellen**, dann **Neue Verbindung erstellen**, dann **Zum Agent
        hinzufügen**.
      </Step>

      <Step title="In Microsoft 365 Copilot veröffentlichen">
        Veröffentliche den Agent und wähle unter **Microsoft 365 aktivieren** die
        Option **Agent in Microsoft 365 Copilot verfügbar machen**. Danach
        erreichen Nutzer Samsa aus der Microsoft-365-Copilot-App und aus Teams.
      </Step>
    </Steps>

    <Note>
      Copilot Studio unterstützt den **Streamable**-Transport, den Samsa bedient.
      Der Zugriff auf MCP server läuft über Power-Platform-Connectors — jede
      Data Policy, die diese regelt, regelt damit auch Samsas Tools.

      Die **Federated Connectors** von Microsoft 365 Copilot sind eine andere
      Funktion und auf lesenden Datenabruf beschränkt. Samsas Generierungs-Tools
      werden wie oben über Copilot Studio eingebunden.
    </Note>
  </Tab>

  <Tab title="Claude Code">
    **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? 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.
  </Tab>

  <Tab title="Cursor">
    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}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    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.
  </Tab>

  <Tab title="Weitere Clients">
    <AccordionGroup>
      <Accordion title="Windsurf" icon="wind">
        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_..." }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Codex (OpenAI)" icon="code-branch">
        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_..." }
        ```
      </Accordion>

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

      <Accordion title="Gemini CLI" icon="gem">
        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_..." }
            }
          }
        }
        ```
      </Accordion>

      <Accordion title="Teste es — MCP Inspector" icon="magnifying-glass">
        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 fünfzehn Tools zu
        listen und einen Testaufruf zu machen.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

<Note>
  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. Wenn ein Schritt daneben liegt,
  schreib an
  [support@samsa.ai](mailto:support@samsa.ai), und wir beheben es schnell.
</Note>