MCP Server

Collega Claude, ChatGPT, Cursor, VS Code o qualsiasi client MCP direttamente al tuo workspace.

---

Questo è il modo strategico di usare SOIS: porta il tuo agente. Il tuo workspace Sois AI è un server MCP completo, quindi l'agente AI che già usi si collega e ragiona direttamente sui tool del tuo workspace. Sempre più spesso le persone non accedono mai alla console SOIS. Dicono al loro Claude, ChatGPT, Cursor o Gemini cosa serve e questo opera su SOIS per loro tramite MCP. La console diventa un luogo per visualizzare e gestire l'attività degli agenti, non il modo principale in cui si lavora.

Qualsiasi client che parla il Protocollo di Contesto del Modello può collegarsi e usare i tool del tuo workspace: cerca contatti, crea task, invia email, gestisci documenti e altro ancora, senza scrivere una sola integrazione. Poiché è il tuo agente a fare il ragionamento, SOIS non spende AI per te.

Un solo endpoint. Protocollo standard. Ogni tool che il tuo account può usare, disponibile per qualsiasi client compatibile.

---

L'unico URL

Il tuo workspace espone un singolo endpoint MCP:

https://<your-workspace>.sois.ai/api/mcp

Il server si identifica con il brand del tuo workspace (per esempio "Acme"), quindi appare con il tuo nome nel client. Tutto il resto dipende da questo unico URL.

Ci sono due modi per autenticarsi. OAuth è il percorso consigliato ed è quello usato dai connettori integrati in Claude e ChatGPT: incolli l'URL, approvi una volta e non c'è nessun token da copiare o ruotare manualmente. È supportato anche un token Bearer più chiave API per script, server e client che non fanno OAuth.

---

Opzione A: OAuth 2.1 (consigliata, niente da incollare)

I connettori MCP moderni scoprono e completano l'intero accesso per te. Devi solo fornire l'URL.

1. Nel tuo client (per esempio Claude o ChatGPT), aggiungi un connettore personalizzato e incolla il tuo URL MCP: https://<your-workspace>.sois.ai/api/mcp

2. Il client chiama l'endpoint senza token e riceve un 401 con una challenge di discovery:

WWW-Authenticate: Bearer resource_metadata="https://<your-workspace>.sois.ai/.well-known/oauth-protected-resource"

3. Il client legge quei metadati, trova il server di autorizzazione del tuo workspace, si registra automaticamente (Dynamic Client Registration) e apre la schermata di accesso e consenso.

4. Approvi la connessione nel tuo account SOIS. Il client riceve un token tramite PKCE (con un refresh token rotante) e inizia a lavorare. Nessun token viene mai copiato a mano.

Perché è sicuro. Il server di autorizzazione è il dominio del tuo workspace, quindi i token sono limitati al tenant e non escono mai dalla tua rete. L'autorizzazione è il tuo ruolo: un token concesso non può mai fare più di quello che puoi fare tu, perché ogni chiamata tool viene controllata dai permessi all'esecuzione. Le stringhe di scope sono volutamente generiche; il confine reale sono i tuoi permessi per utente.

Cosa pubblicizza il server di autorizzazione:

Normalmente non chiami questi endpoint tu stesso; un client MCP conforme percorre il flusso automaticamente una volta che ha l'URL.

---

Opzione B: Token Bearer + chiave API (diretta o lato server)

Per script, server o qualsiasi client che non implementa OAuth. Generi due credenziali e le invii come header a ogni richiesta.

1. Apri Impostazioni > Collega il tuo Agente nel tuo workspace Sois AI.

2. Scegli il tuo client (Claude Desktop, Cursor, VS Code o Generico) e clicca Genera Credenziali per ottenere un token Bearer, una chiave API e uno snippet di configurazione pronto all'uso.

3. Incolla la configurazione nel tuo client.

{
  "mcpServers": {
    "sois-workspace": {
      "url": "https://<your-workspace>.sois.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor usa la stessa struttura in .cursor/mcp.json; VS Code la annida sotto "mcp": { "servers": { ... } } con "type": "http".

Due credenziali perché identità e spesa sono separate: un token dimostra chi sei, la chiave controlla e misura i costi, e una sola delle due è inutile. (I token OAuth gestiscono l'autorizzazione in modo diverso, quindi un connettore dell'Opzione A non ha bisogno dell'header X-Api-Key.)

Genera la coppia programmaticamente quando automatizzi l'onboarding:

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/quick-setup" \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "generic"}'

---

Endpoint di discovery

Un client può apprendere tutto ciò che serve da tre documenti pubblici alla radice del tuo workspace:

La server card riporta authentication.type come oauth2 e collega ai due documenti OAuth, ed è così che un connettore sa di avviare il flusso dell'Opzione A.

---

Dettagli del protocollo

L'endpoint parla Streamable HTTP con JSON-RPC 2.0 (versione della specifica 2025-06-18).

Ciclo di vita della sessione

Includi l'Mcp-Session-Id dalla risposta di initialize in ogni richiesta successiva.

Metodi supportati

---

Quali tool sono disponibili

tools/list restituisce tutto ciò che puoi fare dentro Sois AI, filtrato in base ai tuoi permessi:

• Contacts: search, create, update, summarise
• Tasks: create, assign, update status, search
• Calendar: list, create, update events, check availability
• Documents: search, create, update content
• Files: browse, upload, download
• Inbox: read, compose, send
• Departments and team: list and manage (admin)
• Installed apps: every tool added by the extensions you have installed (CRM, invoicing, warehouse, custom entities, and so on)

L'elenco esatto dipende dal ruolo dell'utente autenticato e dalle app installate. I tool sono filtrati per permessi e falliscono in modo chiuso, quindi una connessione non può mai chiamare qualcosa che l'utente non è autorizzato a usare.

L'app builder funziona sullo stesso endpoint

Non esiste un server MCP separato per creare app. I tool dell'extension-builder fanno parte dello stesso server MCP del workspace e appaiono nello stesso tools/list, con una condizione: sono protetti da admin, quindi appaiono solo per gli account con capacità di builder. Se il tuo account può creare app, il tuo elenco di tool include anche:

• getExtensionRules, getExtensionFrameSpec (what an app must look like)
• createExtensionProject, listExtensionProjects, getExtensionStatus
• validateExtensionBundle, uploadExtensionBundle

Quindi creare un'app è lo stesso atto di tutto il resto: colleghi il tuo agente al tuo workspace una sola volta e, se sei un builder, può creare lo scheletro, validare e pubblicare un'app insieme alla gestione della tua attività, tutto attraverso il solo endpoint /api/mcp. Vedi Crea un'app per il flusso di lavoro.

(Non va confuso con il connettore pubblico di sola lettura per il contesto di build che un operatore può aggiungere per pubblicizzare le capacità di una rete; quello è un endpoint separato e non autenticato sul dominio della rete, non il server MCP del tuo workspace.)

---

Budget, limiti ed errori

Si applicano gli errori JSON-RPC standard, più alcuni codici specifici:

---

Testa la tua connessione

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: YOUR_API_KEY"

Restituisce se le credenziali funzionano e quanti tool sono visibili a esse.

---

Portare il tuo agente è il percorso strategico. Il MCP Server permette al tuo client AI di ragionare direttamente sui tool di SOIS, quindi SOIS non spende AI per te. Il Chat Agent Gateway è il punto di accesso per chi non ha un agente: messaggi in linguaggio naturale su HTTP, dove è l'agente di SOIS a fare il ragionamento. Usa quello che si adatta al tuo interlocutore, o entrambi.

---

Vuoi collegare Sois a server MCP esterni invece? Vedi MCP Gateway per le connessioni in uscita.