Colleghi Claude al software aziendale aggiungendo il server MCP del sistema come connettore personalizzato: apri Personalizza, poi Connettori, scegli Aggiungi connettore personalizzato, incolla l'URL HTTPS del server e accedi quando Claude apre la pagina OAuth del sistema. Da quel momento Claude recupera l'elenco degli strumenti che il sistema ti offre e li chiama come te quando ne ha bisogno. In Claude Code la stessa connessione è un comando, claude mcp add --transport http, seguito da /mcp per accedere.
La condizione è che il software abbia un server MCP. Molti sistemi non ce l'hanno ancora, e una REST API da sola non è sufficiente per questo percorso. Dove esiste un server, la connessione avviene come una persona specifica, quindi ciò che Claude può fare è esattamente ciò che quella persona può fare, e il sistema, non Claude, è quello che lo impone.
Cos'è realmente la connessione
Sono coinvolte tre parti, e nominarle evita la maggior parte della confusione in seguito. L'host è l'applicazione Claude. All'interno di essa, viene creato un client per ogni server a cui ti connetti, e quel client comunica con esattamente un server. Il server è l'endpoint MCP del sistema aziendale, un'unica URL HTTPS che accetta messaggi JSON-RPC. I client di Claude funzionano nel cloud di Anthropic, non sulla tua macchina, motivo per cui il server deve essere raggiungibile da Internet pubblico; un sistema su una rete privata deve avere gli intervalli di indirizzi di Anthropic autorizzati prima che tutto questo funzioni.
L'URL è l'unica cosa che devi conoscere in anticipo. Per uno spazio di lavoro Sois è l'indirizzo dello spazio di lavoro seguito da /api/mcpAltri prodotti pubblicano i loro nella documentazione; uno che termina in /sse Altri prodotti pubblicano i loro nella loro documentazione; uno che termina in "" indica il trasporto più vecchio, che Claude accetta ancora ma che la specifica ora segna come deprecato a favore di Streamable HTTP.
La guida, minuto per minuto
- Incolla l'URLIn Claude, apri Personalizza, poi Connettori, scegli Aggiungi connettore personalizzato, dagli un nome e incolla l'indirizzo HTTPS del server. In Claude Code, esegui invece il comando mcp add.
- Claude interroga il serverClaude invia una richiesta senza credenziali. Un server protetto risponde 401 con un'intestazione WWW-Authenticate che punta ai suoi metadati delle risorse protette. Claude lo legge e segna le impostazioni di autenticazione che ha rilevato.
- Claude trova il server di autorizzazione.I metadati identificano il server di autorizzazione. Claude recupera i metadati di quel server per conoscere gli endpoint di autorizzazione, token e registrazione e il metodo PKCE richiesto.
- Claude si identificaClaude presenta il documento dei metadati del client ospitato da Anthropic, oppure si registra dinamicamente, oppure utilizza un client ID che hai inserito. Non devi fare nulla a meno che tu non abbia scelto l'ultima opzione.
- Accedi e consentiClaude apre la pagina di accesso del sistema nel tuo browser. Ti autentichi come te stesso e approvi gli ambiti mostrati. Il sistema reindirizza con un codice, Claude lo scambia per un token legato a quel server e conserva il token di aggiornamento.
- Claude elenca gli strumentiCon il token allegato, Claude chiama tools/list e riceve gli strumenti che questo sistema ti offre. Appaiono sotto il connettore, ciascuno con un permesso che puoi impostare.
- Prima richiestaChiedi qualcosa. Claude seleziona gli strumenti, richiede approvazione alla prima chiamata a ciascuno a meno che tu non abbia scelto Sempre consenti, e il sistema verifica la chiamata rispetto ai tuoi permessi prima di fare qualsiasi cosa.
I passaggi due a cinque sono il flusso OAuth 2.1 richiesto dalla specifica di autorizzazione MCP per i server HTTP, e il motivo per cui non c'è un token da incollare. La sfida 401 appare così sulla rete, con l'indirizzo dei metadati e, facoltativamente, gli ambiti richiesti dal server.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://acme.sois.ai/.well-known/oauth-protected-resource",
scope="mcp"La sfida che un workspace Sois restituisce a un client non autenticato. Il client segue l'indirizzo resource_metadata per scoprire il server di autorizzazione; il valore dell'ambito è il minimo privilegio che dovrebbe richiedere per primo.
Due regole del protocollo ti proteggono qui senza il tuo coinvolgimento. Il client deve richiedere un token per questo specifico server, utilizzando il parametro resource della RFC 8707, e il server deve rifiutare i token emessi per qualsiasi altra cosa, quindi un token per un sistema non può essere riutilizzato su un altro. E il server non deve mai passare il tuo token a un terzo servizio. La specifica tratta entrambi come requisiti vincolanti, non raccomandazioni.
Scelta del metodo di accesso
La finestra di dialogo Aggiungi connettore personalizzato di Claude offre un piccolo insieme di scelte una volta che ha sondato l'URL. La maggior parte delle persone non cambia ciò che rileva, ma è utile sapere cosa significa ciascuna opzione, poiché le impostazioni di autenticazione non possono essere modificate in seguito; per cambiarle, devi rimuovere il connettore e aggiungerlo di nuovo.
| Impostazione | Opzioni | Quando utilizzare |
|---|---|---|
| Autenticazione | Sempre richiesto; Richiesto quando il server lo richiede; Nessuno | Sempre richiesto per qualsiasi cosa che agisca come una persona. Nessuno solo per un server interno in sola lettura, con la chiave API inserita nelle intestazioni della richiesta. |
| Client OAuth | Metadati del client ospitato di Anthropic; registrazione automatica; il tuo ID client | Il documento ospitato è raccomandato quando il server lo supporta. La registrazione automatica funziona con la maggior parte dei server ma accumula registrazioni. Il tuo ID quando il sistema insiste sulla pre-registrazione. |
| Intestazioni della richiesta | Fino a quattro intestazioni fisse come x-api-key | Credenziali condivise per un account di servizio, o un'intestazione di instradamento necessaria a un gateway. In beta e non mostrata a tutte le organizzazioni. |
| Trasporto | Imposta dall'URL | Lascialo. Un URL che termina con /sse seleziona il trasporto più vecchio; cambialo solo se la documentazione del server lo indica. |
Per un sistema aziendale, la risposta giusta è quasi sempre il predefinito: OAuth, sempre richiesto, un accesso per persona. Le intestazioni condivise fanno sembrare ogni azione come se fosse dello stesso utente nel log.
Per i piani Team ed Enterprise, la forma è la stessa con un passaggio aggiuntivo: un proprietario aggiunge il connettore nelle impostazioni dell'organizzazione, e ogni membro si connette e accede come se stesso sotto Personalizza. Il proprietario decide quali server esistono; le azioni del membro portano comunque l'autorità del membro stesso.
Cosa vede Claude dopo la connessione
La lista degli strumenti è l'intera interfaccia. Ogni voce ha un nome, una descrizione e uno schema di input, e il modello di Claude utilizza le descrizioni per decidere quale strumento è necessario per una richiesta e lo schema per compilare gli argomenti. In uno spazio di lavoro Sois, la lista è filtrata in base al tuo ruolo e alle app installate prima di essere restituita, quindi un utente finanziario vede strumenti come cercaFatture, crea fattura, registraPagamento e inviaPromemoriaFatture, insieme ai contatti, alla posta in arrivo, al calendario e agli strumenti per le attività che tutti hanno, e non vede affatto gli strumenti amministrativi. La specifica consente esattamente questo: un server può variare l'elenco in base alle credenziali nella richiesta.
Claude poi sovrappone i propri controlli. Sotto il connettore puoi impostare qualsiasi strumento su Bloccato, così il modello non lo vede mai. In chat, ogni chiamata a uno strumento richiede approvazione a meno che tu non abbia scelto Sempre consenti per quello strumento, che Anthropic consiglia di riservare per i server di cui ti fidi. Le funzionalità di ricerca possono invocare strumenti del connettore senza chiedere, quindi la guida è di disattivare gli strumenti di scrittura sul connettore mentre è in corso un'operazione di ricerca.
La stessa connessione da Claude Code e dall'API
Nel codice di Claude il comando è claude mcp add --transport http sois https://your-workspace.sois.ai/api/mcp. Il server è memorizzato a livello locale per impostazione predefinita; --scope progetto lo scrive in un .mcp.json puoi impegnarti per il team, e --scope utente lo rende disponibile in ogni progetto. Esegui /mcp per accedere tramite il browser, oppure claude mcp login sois dalla shell. I connettori già aggiunti su claude.ai appaiono automaticamente in Claude Code sotto lo stesso account, e gli amministratori possono contrassegnare singoli strumenti come richiesti o bloccati.
L'API dei Messaggi è di tipo diverso. Il suo connettore MCP, in beta dietro il mcp-client-2025-11-20 intestazione, prende l'URL del server in un mcp_servers ingresso e un mcp_toolset nell'array degli strumenti, e supporta solo le chiamate agli strumenti. Non c'è flusso del browser: ottieni tu stesso il token di accesso OAuth e lo passi come token di autorizzazione, aggiornandolo secondo necessità. Questo si adatta a un servizio che gestisci per conto di utenti che hai già autenticato. È la strada sbagliata per fornire a un utente finale una connessione, che è ciò per cui esiste il connettore personalizzato.
Cosa può fare Claude
Dopo la guida, la domanda utile non è se Claude sia connesso, ma cosa possa fare la connessione, e la risposta è stabilita dal server. Su Sois la risposta sono i permessi di una persona, applicati due volte: una volta quando viene assemblata la lista degli strumenti, una volta quando ogni chiamata viene eseguita. Il token è stato emesso a te, quindi ogni azione è attribuita a te nel registro del workspace con i suoi input e il suo risultato, esattamente come sarebbe per una persona. La spesa è limitata per integrazione dove l'agente del workspace svolge lavoro; quando Claude fa il ragionamento, come fa attraverso questa connessione, il workspace non esegue alcuna IA per tuo conto e non addebita nulla per questo.
Questo è ciò che rende ragionevole lasciare che un modello agisca: i permessi sono quelli che l'azienda già mantiene per le persone, e la connessione li eredita.
Quando qualcosa va storto
- I loop di accesso o i fallimenti. Quasi sempre l'URL: un percorso che non è l'endpoint MCP, o un server non raggiungibile da internet pubblico. Controlla l'indirizzo rispetto alla documentazione del sistema e conferma che risponda 401 con un'intestazione WWW-Authenticate.
- Gli strumenti mancano. L'elenco è filtrato in base al tuo ruolo. Se un collega vede uno strumento che tu non vedi, la differenza sono i permessi nel sistema aziendale, non il connettore.
- Una chiamata è rifiutata. Leggi l'errore segnalato da Claude. Un rifiuto di permesso significa che la persona con cui hai effettuato l'accesso non può farlo; un errore di convalida significa che il modello può correggere l'input e riprovare.
Domande che le persone pongono
Devo incollare una chiave API o un token in Claude?
Non per un server che supporta OAuth. Claude scopre il server di autorizzazione dalla sfida 401 e apre una pagina di accesso; il token viene emesso a Claude e aggiornato automaticamente. Le intestazioni fisse sono solo per server che non hanno OAuth, e le credenziali condivise perdono l'attribuzione per persona.
Posso connettere software che ha solo un'API REST?
Non attraverso questo percorso. I connettori personalizzati di Claude parlano MCP. Qualcuno deve mettere un server MCP davanti all'API, che è ciò che piattaforme come Sois fanno per l'intera superficie degli strumenti.
La connessione funziona da Claude sul mio telefono?
La documentazione di Anthropic elenca Claude web, l'app desktop e Cowork per i connettori personalizzati. Poiché il client gira nel cloud di Anthropic piuttosto che sul dispositivo, un connettore aggiunto sul web non è legato a una macchina.
Cosa può fare Claude una volta connesso?
Qualsiasi cosa la persona con cui hai effettuato l'accesso può fare in quel sistema, a condizione che il server imponga permessi su ogni chiamata. Su Sois ciò significa gli strumenti del tuo ruolo attraverso contatti, casella di posta, contabilità, attività e altro, controllati quando offerti e di nuovo quando eseguiti.
- Documentazione di Claude: connettori di terze parti con MCP remoto la finestra di dialogo Aggiungi connettore personalizzato campo per campo, e i controlli per strumento
- specifica del Model Context Protocol: autorizzazione il flusso OAuth 2.1, i metadati delle risorse protette, gli indicatori delle risorse e le regole del token
- Documentazione di Claude Code: server MCP il comando add di claude mcp, gli ambiti e l'accesso
- Documentazione Sois: il server MCP dello spazio di lavoro l'endpoint, i documenti di scoperta e il filtraggio dei ruoli come implementato
Questo articolo viene revisionato quando i prodotti che descrive cambiano. Prossima revisione programmata: 4 dicembre 2026.