Questa pagina copre la configurazione di MCP per l’Agent SDK. Per aggiungere server MCP al Claude Code CLI in modo che si carichino in ogni progetto, consulta Ambiti di installazione di MCP.
Quickstart
Questo esempio si connette al server MCP della documentazione di Claude Code utilizzando il trasporto HTTP e utilizzaallowedTools con un carattere jolly per consentire tutti gli strumenti dal server.
Aggiungi un server MCP
Puoi configurare i server MCP nel codice quando chiamiquery(), oppure in un file .mcp.json caricato tramite settingSources.
Nel codice
Passa i server MCP direttamente nell’opzionemcpServers:
Da un file di configurazione
Crea un file.mcp.json nella radice del tuo progetto. Il file viene rilevato quando la fonte di impostazione project è abilitata, il che è il caso per le opzioni predefinite di query(). Se imposti settingSources esplicitamente, includi "project" affinché questo file venga caricato:
Consenti strumenti MCP
Gli strumenti MCP richiedono un’autorizzazione esplicita prima che Claude possa utilizzarli. Senza autorizzazione, Claude vedrà che gli strumenti sono disponibili ma non sarà in grado di chiamarli.Convenzione di denominazione degli strumenti
Gli strumenti MCP seguono il modello di denominazionemcp__<server-name>__<tool-name>. Ad esempio, un server GitHub denominato "github" con uno strumento list_issues diventa mcp__github__list_issues.
Approvazione automatica con allowedTools
UtilizzaallowedTools per approvare automaticamente strumenti MCP specifici in modo che Claude possa utilizzarli senza un prompt di autorizzazione:
*) ti permettono di consentire tutti gli strumenti da un server senza elencare ciascuno individualmente.
Preferisci
allowedTools rispetto alle modalità di autorizzazione per l’accesso a MCP. permissionMode: "acceptEdits" non approva automaticamente gli strumenti MCP (solo le modifiche ai file e i comandi Bash del filesystem). permissionMode: "bypassPermissions" approva automaticamente gli strumenti MCP ma disabilita anche tutti gli altri prompt di sicurezza, il che è più ampio del necessario. Un carattere jolly in allowedTools concede esattamente il server MCP che desideri e niente di più. Consulta Modalità di autorizzazione per un confronto completo.Scopri gli strumenti disponibili
Per vedere quali strumenti fornisce un server MCP, controlla la documentazione del server o connettiti al server e ispeziona il messaggio di inizializzazionesystem:
Tipi di trasporto
I server MCP comunicano con il tuo agente utilizzando diversi protocolli di trasporto. Controlla la documentazione del server per vedere quale trasporto supporta:- Se la documentazione ti fornisce un comando da eseguire (come
npx @modelcontextprotocol/server-github), utilizza stdio - Se la documentazione ti fornisce un URL, utilizza HTTP o SSE
- Se stai costruendo i tuoi strumenti personalizzati nel codice, utilizza un server MCP SDK
Server stdio
Processi locali che comunicano tramite stdin/stdout. Utilizza questo per i server MCP che esegui sulla stessa macchina:- Nel codice
- .mcp.json
Server HTTP/SSE
Utilizza HTTP o SSE per i server MCP ospitati nel cloud e le API remote:- Nel codice
- .mcp.json
"type": "http" invece. Nei file di configurazione .mcp.json e altri file JSON, "streamable-http" è accettato come alias per "http". L’opzione programmatica mcpServers accetta solo "http".
Server MCP SDK
Definisci strumenti personalizzati direttamente nel codice della tua applicazione invece di eseguire un processo server separato. Consulta la guida agli strumenti personalizzati per i dettagli di implementazione.Ricerca di strumenti MCP
Quando hai molti strumenti MCP configurati, le definizioni degli strumenti possono consumare una parte significativa della tua finestra di contesto. La ricerca di strumenti risolve questo problema trattenendo le definizioni degli strumenti dal contesto e caricando solo quelli di cui Claude ha bisogno per ogni turno. La ricerca di strumenti è abilitata per impostazione predefinita. Consulta Ricerca di strumenti per le opzioni di configurazione e i dettagli. Per ulteriori dettagli, incluse le best practice e l’utilizzo della ricerca di strumenti con strumenti SDK personalizzati, consulta la guida alla ricerca di strumenti.Autenticazione
La maggior parte dei server MCP richiede l’autenticazione per accedere ai servizi esterni. Passa le credenziali tramite variabili di ambiente nella configurazione del server.Passa le credenziali tramite variabili di ambiente
Utilizza il campoenv per passare chiavi API, token e altre credenziali al server MCP:
- Nel codice
- .mcp.json
Intestazioni HTTP per server remoti
Per i server HTTP e SSE, passa le intestazioni di autenticazione direttamente nella configurazione del server:- Nel codice
- .mcp.json
Autenticazione OAuth2
La specifica MCP supporta OAuth 2.1 per l’autorizzazione. L’SDK non gestisce i flussi OAuth automaticamente, ma puoi passare i token di accesso tramite intestazioni dopo aver completato il flusso OAuth nella tua applicazione:Esempi
Elenca i problemi da un repository
Questo esempio si connette al server GitHub MCP per elencare i problemi recenti. L’esempio include la registrazione di debug per verificare la connessione MCP e le chiamate agli strumenti. Prima di eseguire, crea un token di accesso personale GitHub con ambitorepo e impostalo come variabile di ambiente:
Interroga un database
Questo esempio utilizza il server Postgres MCP per interrogare un database. La stringa di connessione viene passata come argomento al server. L’agente scopre automaticamente lo schema del database, scrive la query SQL e restituisce i risultati:Gestione degli errori
I server MCP possono non riuscire a connettersi per vari motivi: il processo del server potrebbe non essere installato, le credenziali potrebbero non essere valide o un server remoto potrebbe essere irraggiungibile. L’SDK emette un messaggiosystem con sottotipo init all’inizio di ogni query. Questo messaggio include lo stato della connessione per ogni server MCP. Controlla il campo status per rilevare gli errori di connessione prima che l’agente inizi a lavorare:
Troubleshooting
Il server mostra lo stato “failed”
Controlla il messaggioinit per vedere quali server non hanno potuto connettersi:
- Variabili di ambiente mancanti: Assicurati che i token e le credenziali richiesti siano impostati. Per i server stdio, controlla che il campo
envcorrisponda a quello che il server si aspetta. - Server non installato: Per i comandi
npx, verifica che il pacchetto esista e che Node.js sia nel tuo PATH. - Stringa di connessione non valida: Per i server di database, verifica il formato della stringa di connessione e che il database sia accessibile.
- Problemi di rete: Per i server HTTP/SSE remoti, controlla che l’URL sia raggiungibile e che eventuali firewall consentano la connessione.
Gli strumenti non vengono chiamati
Se Claude vede gli strumenti ma non li utilizza, controlla di aver concesso l’autorizzazione conallowedTools:
Timeout della connessione
L’SDK MCP ha un timeout predefinito di 60 secondi per le connessioni del server. Se il tuo server impiega più tempo per avviarsi, la connessione avrà esito negativo. Per i server che hanno bisogno di più tempo di avvio, considera:- Utilizzare un server più leggero se disponibile
- Pre-riscaldare il server prima di avviare il tuo agente
- Controllare i log del server per le cause di inizializzazione lenta
Risorse correlate
- Guida agli strumenti personalizzati: Costruisci il tuo server MCP che viene eseguito in-process con la tua applicazione SDK
- Autorizzazioni: Controlla quali strumenti MCP il tuo agente può utilizzare con
allowedToolsedisallowedTools - Riferimento SDK TypeScript: Riferimento API completo incluse le opzioni di configurazione di MCP
- Riferimento SDK Python: Riferimento API completo incluse le opzioni di configurazione di MCP
- Directory dei server MCP: Sfoglia i server MCP disponibili per database, API e altro