Un server MCP aggiunge capacità che il modello non ha e, insieme, un punto di rottura in più: un processo da avviare, credenziali da rinnovare, una connessione che può cadere a metà sessione. La domanda di progetto non è quali server collegare, ma quali capacità non sono già coperte dai tool nativi che l’agente porta con sé.

Dove metti la configurazione decide chi la eredita

Si aggiunge un server con claude mcp add, scegliendo il trasporto. Per un server remoto si passa un URL con --transport http; il trasporto SSE esiste ancora ma «The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available». Per un processo locale si usa stdio, e il doppio trattino non è cosmetico: «the -- (double dash) separates Claude’s own options, such as --transport, --env, and --scope, from the command and arguments that run the server».

Gli scope sono tre e cambiano chi vede il server. Locale è il default, vale solo per il progetto corrente e non è condiviso. Utente vale in tutti i tuoi progetti, sempre senza condivisione. Progetto scrive un file .mcp.json nella radice ed è l’unico che viaggia con il codice: «Check .mcp.json into version control so everyone on your team gets the same MCP tools and services». Le credenziali non vanno però nel file, perché la configurazione espande le variabili d’ambiente, con un default opzionale.

${API_KEY}                          espande la variabile API_KEY
${API_BASE_URL:-https://api.example.com}   usa il default se non impostata

I tool esposti prendono un nome qualificato nella forma mcp__<nome-server>__<nome-tool>, ed è quel nome che userai nelle liste di autorizzazione.

«pending» non è un guasto

In produzione il fallimento tipico non è il tool che sbaglia, è il server che non c’è. «MCP servers can fail to connect for various reasons: the server process might not be installed, credentials might be invalid, or a remote server might be unreachable.» Il messaggio di init riporta uno stato per ciascun server, e va letto con attenzione perché uno stato in attesa può significare tre cose diverse: connessione non ancora avvenuta, elenco dei tool servito dalla cache con collegamento rimandato al primo uso, oppure scadenza del termine. I due stati che indicano un server inutilizzabile sono il fallimento e la richiesta di autenticazione.

I numeri da tenere a mente: «MCP server connections time out after 30 seconds by default», e per un server remoto che perde la connessione a sessione avviata «After five reconnection attempts fail» lo stato diventa definitivo. La ragione per cui questo controllo va scritto e non saltato sta in una riga della stessa pagina: «since Claude can fall back to built-in tools when the server is unavailable». Un agente che credevi stesse interrogando il database sta leggendo file.

I tool nativi non sono intercambiabili

Quel fallback merita di essere capito, perché i sei tool nativi hanno comportamenti precisi e costi diversi. Read, Grep e Glob non richiedono permesso; Write, Edit e Bash sì.

Glob trova file per nome, Grep trova righe dentro i file. La differenza che fa perdere più tempo è un’altra: Grep rispetta il file di ignore di git, «so gitignored files are skipped», mentre Glob non lo fa di default, «so it finds gitignored files alongside tracked ones». Glob ordina per data di modifica e i risultati sono «sorted by modification time and capped at 100 files»: superato il tetto la ricerca va ristretta, non ripetuta. Grep, poi, «uses ripgrep’s regex syntax, not POSIX grep», quindi i metacaratteri vanno protetti.

Read restituisce il contenuto numerato per riga e vuole percorsi assoluti; su file grandi torna una prima pagina parziale con l’indicazione di come proseguire per intervalli. «Read only reads files, not directories.» Edit «performs exact string replacement»: niente regex, niente fuzzy matching, e tre condizioni da soddisfare, cioè lettura preventiva del file nella conversazione corrente, corrispondenza esatta della stringa e unicità dell’occorrenza.

Bash è il tool con più stato implicito. «The Bash tool runs each command in a separate process»: la directory corrente sopravvive fra comandi, ma «Environment variables don’t persist», quindi un export non arriva al comando successivo. Il timeout di default è di due minuti con un tetto di dieci. L’asimmetria che conviene conoscere prima di costruirci sopra una pipeline riguarda l’output: un comando riuscito arriva inline fino a circa 30.000 caratteri e oltre viene salvato su file di cui ricevi il percorso; un comando fallito ne riceve inline circa 10.000, come estratto di testa e coda, e senza alcun percorso di file.

Il contesto è il vincolo, non la capacità

Ogni tool esterno restituisce testo che resta nel contesto. Claude Code impone un tetto: un risultato MCP oltre i 25.000 token viene salvato su file e sostituito da un errore che ne indica il percorso, così l’agente lo rilegge a pezzi. Il tetto si alza con una variabile d’ambiente, ma alzarlo sposta il problema invece di risolverlo.

Lo stesso ragionamento vale al contrario, ed è il motivo per cui non tutto merita un server MCP: «CLI tools are the most context-efficient way to interact with external services». Un gh già installato costa meno di un server che espone gli stessi endpoint. Per l’esplorazione, invece, la leva è la delega: «Subagents run in separate context windows and report back summaries».

Un dettaglio operativo sulle regole di negazione in lettura: coprono i tool nativi e i comandi shell riconosciuti quando il percorso vietato è passato come argomento, ma «Claude still sees denied paths in the output of a Bash search such as grep -r or find». Il divieto non è un confine di sicurezza.

Chi può chiamare cosa

«MCP tools require explicit permission before Claude can use them. Without permission, Claude will see that tools are available but won’t be able to call them.» L’autorizzazione si concede per nome qualificato o con un carattere jolly per l’intero server. Non usare i permission mode come scorciatoia: la modalità che accetta le modifiche «does not auto-approve MCP tools (only file edits and filesystem Bash commands)», mentre quella che aggira i permessi li approva insieme a quasi tutto il resto.

Resta la valutazione che nessuna configurazione fa al posto tuo: «Verify you trust each server before connecting it.» Un server che recupera contenuti esterni porta quei contenuti nel contesto dell’agente.