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

# Connect your client

> One-time setup for Claude, ChatGPT, Microsoft Copilot, Claude Code, Cursor, VS Code, n8n, and more.

Add `https://api.samsa.ai/mcp` to your client below. **Claude**, **ChatGPT**, and
**Microsoft Copilot** can sign in with OAuth; the remaining clients authenticate
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">
    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">
    <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="Microsoft Copilot">
    Microsoft connects MCP servers through **Copilot Studio**. Add Samsa there
    once, then publish the agent to the **Microsoft 365 Copilot and Teams**
    channel so your organization uses it from Copilot chat and Teams.

    <Steps>
      <Step title="Add the server">
        On your agent's **Tools** page, select **Add a tool → New tool → Model
        Context Protocol**. Set **Server URL** to `https://api.samsa.ai/mcp` and
        give the server a name and description.

        The agent's orchestrator reads that description to decide when to call
        Samsa, so be concrete — for example, "Generates and edits images and video
        using the organization's trained Samsa models."
      </Step>

      <Step title="Pick an authentication type">
        Samsa works with either option the wizard offers:

        * **OAuth 2.0 → Dynamic discovery** — Samsa supports dynamic client
          registration with discovery, so Copilot Studio finds the endpoints and
          registers itself. Each user signs in with their own Samsa account and no
          key is shared.
        * **API key** — set **Type** to **Header** and the header name to
          `Authorization`. The connection value is `Bearer samsa_sk_…`.
      </Step>

      <Step title="Create the connection">
        Select **Create**, then **Create a new connection**, then **Add to agent**.
      </Step>

      <Step title="Publish to Microsoft 365 Copilot">
        Publish the agent and, under **Turn on Microsoft 365**, select **Make agent
        available in Microsoft 365 Copilot**. Users then reach Samsa from the
        Microsoft 365 Copilot app and Teams.
      </Step>
    </Steps>

    <Note>
      Copilot Studio supports the **Streamable** transport, which is what Samsa
      serves. Access to MCP servers runs through Power Platform connectors, so any
      data policy governing those also governs Samsa's tools.

      Microsoft 365 Copilot's **federated connectors** are a different feature,
      scoped to read-only data retrieval. Samsa's generation tools are added
      through Copilot Studio as above.
    </Note>
  </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? Run `claude mcp add --transport http samsa
            https://api.samsa.ai/mcp` **without** the header and complete the OAuth
    sign-in on first use.
  </Tab>

  <Tab title="Cursor">
    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">
    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" icon="wind">
        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)" icon="code-branch">
        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" icon="diagram-project">
        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" icon="gem">
        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="Test it — MCP Inspector" icon="magnifying-glass">
        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 fifteen tools, and make a test call.
      </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. If a step is off, email
  [support@samsa.ai](mailto:support@samsa.ai) and we'll fix it fast.
</Note>