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

# Collega il tuo client

> Configurazione una tantum per Claude, ChatGPT, Microsoft Copilot, Cursor, VS Code, n8n e altri.

Aggiungi `https://api.samsa.ai/mcp` al tuo client qui sotto. **Claude**, **ChatGPT**
e **Microsoft Copilot** possono accedere con OAuth; gli altri client si autenticano
con una [API key](/it/guides/authentication) (`Authorization: Bearer samsa_sk_…`).

<Warning>
  Gli snippet con API key qui sotto mostrano la chiave inline per leggibilità. In
  qualsiasi configurazione che viene committata o condivisa, **non memorizzare una
  chiave reale** — usa l'interpolazione delle variabili d'ambiente del tuo client
  (mostrata per Claude Code, Cursor e VS Code) oppure mantieni la configurazione a
  livello utente. Una `samsa_sk_…` trapelata va
  [revocata](/it/guides/authentication#ruotare-una-chiave) immediatamente.
</Warning>

<Tabs>
  <Tab title="Claude">
    Claude (web e desktop) si connette agli MCP server remoti come **custom
    connector**:

    <Steps>
      <Step title="Aggiungi il connector">
        Apri **Settings → Connectors → Add custom connector** e imposta l'URL a
        `https://api.samsa.ai/mcp`.
      </Step>

      <Step title="Accedi">
        Claude apre l'**accesso OAuth** di Samsa; accedi e approva la schermata di
        consenso. La lista degli strumenti di Claude mostra poi gli strumenti Samsa.
      </Step>
    </Steps>

    Le etichette esatte dei menu variano a seconda della versione — l'essenziale è il
    flusso del custom connector e il server URL di Samsa. Claude web chiama `/mcp` dal
    browser con `Origin: https://claude.ai`, che Samsa consente, così discovery e
    accesso funzionano senza configurazione aggiuntiva. Su desktop, segui le istruzioni
    correnti di Anthropic per i connector e usa lo stesso server URL.
  </Tab>

  <Tab title="ChatGPT">
    <Steps>
      <Step title="Abilita la developer mode">
        In ChatGPT, apri **Settings → Apps & Connectors** e abilita la **developer
        mode**.
      </Step>

      <Step title="Aggiungi la connessione">
        Aggiungi una connessione app / MCP con l'URL `https://api.samsa.ai/mcp`.
      </Step>

      <Step title="Accedi">
        ChatGPT esegue l'accesso e il consenso **OAuth 2.1**; approvalo per esporre
        gli strumenti Samsa.
      </Step>
    </Steps>

    Le etichette esatte dei menu variano a seconda della versione — l'essenziale è
    abilitare la developer mode e aggiungere il server URL di Samsa. Le connessioni MCP
    personalizzate richiedono un piano ChatGPT che includa la developer mode /
    connector; la disponibilità cambia nel tempo, quindi controlla il tuo piano se
    l'opzione manca. ChatGPT chiama `/mcp` con `Origin: https://chatgpt.com` (o
    `https://chat.openai.com`), entrambi consentiti da Samsa.
  </Tab>

  <Tab title="Microsoft Copilot">
    Microsoft collega gli MCP server tramite **Copilot Studio**. Aggiungi Samsa lì
    una volta, poi pubblica l'agent sul canale **Microsoft 365 Copilot e Teams**
    così la tua organizzazione lo usa da Copilot chat e Teams.

    <Steps>
      <Step title="Aggiungi il server">
        Nella pagina **Strumenti** del tuo agent, scegli **Aggiungi uno strumento →
        Nuovo strumento → Model Context Protocol**. Imposta **URL del server** su
        `https://api.samsa.ai/mcp` e dai al server un nome e una descrizione.

        L'orchestratore dell'agent legge quella descrizione per decidere quando
        chiamare Samsa, quindi sii concreto — per esempio "Genera e modifica
        immagini e video con i modelli Samsa addestrati dell'organizzazione".
      </Step>

      <Step title="Scegli un tipo di autenticazione">
        Samsa funziona con entrambe le opzioni della procedura guidata:

        * **OAuth 2.0 → Dynamic discovery** — Samsa supporta la registrazione
          dinamica del client con discovery, così Copilot Studio trova gli endpoint
          e si registra da solo. Ogni persona accede con il proprio account Samsa e
          non viene condivisa alcuna chiave.
        * **API key** — imposta **Tipo** su **Header** e il nome dell'header su
          `Authorization`. Il valore della connessione è `Bearer samsa_sk_…`.
      </Step>

      <Step title="Crea la connessione">
        Scegli **Crea**, poi **Crea una nuova connessione**, poi **Aggiungi
        all'agent**.
      </Step>

      <Step title="Pubblica su Microsoft 365 Copilot">
        Pubblica l'agent e, sotto **Attiva Microsoft 365**, seleziona **Rendi
        l'agent disponibile in Microsoft 365 Copilot**. Gli utenti raggiungono così
        Samsa dall'app Microsoft 365 Copilot e da Teams.
      </Step>
    </Steps>

    <Note>
      Copilot Studio supporta il transport **Streamable**, quello che Samsa serve.
      L'accesso agli MCP server passa dai connettori Power Platform, quindi ogni
      data policy che li governa governa anche gli strumenti di Samsa.

      I **federated connector** di Microsoft 365 Copilot sono una funzionalità
      diversa, limitata al recupero di dati in sola lettura. Gli strumenti di
      generazione di Samsa si aggiungono tramite Copilot Studio come sopra.
    </Note>
  </Tab>

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

    Aggiungi il server con il transport HTTP e un header Bearer:

    ```bash theme={null}
    claude mcp add --transport http samsa https://api.samsa.ai/mcp \
      --header "Authorization: Bearer samsa_sk_..."
    ```

    Per impostazione predefinita questo registra il server solo per il tuo uso (local
    scope). Per condividerlo con il tuo team, aggiungi `--scope project` e Claude Code
    scrive un file `.mcp.json` di progetto. Poiché quel file viene committato, tieni la
    chiave fuori da esso — Claude Code espande le variabili d'ambiente in `headers`:

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

    Conferma la connessione con `claude mcp get samsa` — dovrebbe riportare
    **Connected**.

    Preferisci OAuth? Esegui `claude mcp add --transport http samsa
            https://api.samsa.ai/mcp` **senza** l'header e completa l'accesso OAuth al primo
    uso.
  </Tab>

  <Tab title="Cursor">
    Aggiungi a `~/.cursor/mcp.json` (globale) o al `.cursor/mcp.json` di progetto.
    Cursor interpola le variabili d'ambiente in `headers`, quindi fai riferimento alla
    chiave invece di inserirla inline in un file condiviso:

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

  <Tab title="VS Code">
    Aggiungi a `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "samsa": {
          "type": "http",
          "url": "https://api.samsa.ai/mcp",
          "headers": { "Authorization": "Bearer samsa_sk_..." }
        }
      }
    }
    ```

    Non committare una chiave reale in un file di workspace. VS Code supporta le
    variabili `${input:...}` e la configurazione MCP a livello utente — usa una di
    queste così il segreto non viene incluso nel controllo di versione con il tuo
    progetto.
  </Tab>

  <Tab title="Altri client">
    <AccordionGroup>
      <Accordion title="Windsurf" icon="wind">
        Aggiungi a `~/.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">
        Aggiungi a `~/.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">
        Nel nodo **MCP Client**, imposta:

        * **Endpoint** — `https://api.samsa.ai/mcp`
        * **Transport** — `HTTP Streamable`
        * **Authentication** — Header Auth con `Authorization: Bearer samsa_sk_...`

        n8n gira lato server (nessun header `Origin` del browser), quindi si connette
        senza alcuna configurazione aggiuntiva.
      </Accordion>

      <Accordion title="Gemini CLI" icon="gem">
        Aggiungi un MCP server HTTP a `~/.gemini/settings.json`. I nomi delle chiavi di
        configurazione differiscono tra le versioni di Gemini CLI — verifica rispetto
        alla documentazione MCP corrente di Gemini CLI — ma la forma è l'URL di Samsa
        più un header Bearer:

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

      <Accordion title="Provalo — MCP Inspector" icon="magnifying-glass">
        Per verificare il server da uno strumento neutrale, usa l'
        [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Guidalo
        dalla GUI (o da un file di configurazione) con il transport Streamable-HTTP:

        ```json theme={null}
        {
          "mcpServers": {
            "samsa": {
              "type": "streamable-http",
              "url": "https://api.samsa.ai/mcp",
              "headers": { "Authorization": "Bearer samsa_sk_..." }
            }
          }
        }
        ```

        L'Inspector usa lo stesso transport Streamable-HTTP contro cui Samsa verifica e
        gira su `http://localhost:6274`, che Samsa consente. Usalo per percorrere
        l'handshake, elencare i quindici strumenti e fare una chiamata di prova.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

<Note>
  Gli snippet di configurazione per Claude Code, Cursor, VS Code, Windsurf, Codex,
  n8n, Claude web, ChatGPT e l'MCP Inspector provengono dalla matrice di verifica delle
  configurazioni client del backend di Samsa. Se un passaggio è sbagliato, scrivi a
  [support@samsa.ai](mailto:support@samsa.ai) e lo correggeremo in fretta.
</Note>