Aggiungere un server MCP a Claude Code e Codex

🔍 Cos'è un server MCP e come si aggiunge

Il Model Context Protocol (MCP) è lo standard aperto che collega un assistente AI a strumenti esterni: un server MCP espone tool, risorse e prompt che l'agente può richiamare — navigare una pagina, leggere un database, chiamare un'API. Aggiungerne uno a Claude o a Codex significa dare all'agente nuove capacità concrete.

La buona notizia è che il meccanismo è quasi identico nei due strumenti: c'è sempre un comando per gestire i server e un file dove vengono elencati. Per mostrarlo uso un solo esempio, il server Playwright che pilota un browser, così vedi la stessa operazione prima su Claude e poi su Codex.

# Un solo pacchetto, lo stesso per Claude e per Codex
npx @playwright/mcp@latest

⌨️ Claude Code: il comando /mcp

Partiamo da Claude Code. Dentro una sessione, il comando /mcp apre un pannello interattivo: elenca i server configurati, mostra lo stato della connessione, quanti tool espone ciascuno e permette di autenticare quelli protetti da OAuth.

È il primo posto dove guardare quando un server non risponde: se accanto al nome leggi needs login o failed, il problema è lì, non nel tuo prompt. Dal pannello riavvii, disconnetti o autentichi un server senza aprire nessun file.

🛠️ Claude Code: list, add e remove da terminale

Fuori dalla sessione la gestione passa dal sottocomando claude mcp. I tre che userai sempre: list per vedere cosa è configurato, add per aggiungere un server, remove per toglierlo; con get ispezioni un singolo server.

Il flag che conta è --scope (o -s): local vale solo per te in questo progetto, project finisce in un file versionabile e condiviso col team, user vale per tutti i tuoi progetti. Scegli l'ambito prima di aggiungere, non dopo.

• list — elenca i server e il loro stato.
• add — aggiunge un server (stdio o http).
• remove — rimuove un server dall'ambito scelto.

# Elenca, ispeziona, rimuovi
claude mcp list
claude mcp get playwright
claude mcp remove playwright

# Aggiungi un server stdio: tutto dopo -- è il comando da avviare
claude mcp add playwright -- npx @playwright/mcp@latest

# ...con ambito esplicito e una variabile d'ambiente
claude mcp add -s project -e API_KEY=*** github -- npx -y github-mcp-server

⚙️ Claude Code: il file di configurazione

Ogni server aggiunto finisce in un file JSON. A livello utente è ~/.claude.json; a livello progetto è .mcp.json nella radice del repo — quello che condividi col team. La chiave è una sola, mcpServers, con una voce per server.

Una voce stdio ha command e args (come avviare il processo); una voce http ha type e url per un server remoto. I token non si scrivono mai in chiaro: passali dalle variabili d'ambiente, come nell'esempio annotato qui sotto.

🧱 Claude Code: aggiungere Playwright passo-passo

Mettiamo tutto insieme. Per aggiungere Playwright a Claude basta una riga: il nome del server, poi --, poi il comando che lo avvia. Claude lo registra, lo avvia e ne scopre i tool al volo.

Verifica subito con claude mcp list — deve comparire playwright — oppure apri /mcp in sessione. Se invece leggi spawn npx ENOENT Node o npx non sono nel PATH: è l'errore più comune, e non dipende da MCP.

claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list
#  playwright   ✔ connected · 21 tools

🔌 Codex: aggiungere un MCP dal terminale

Passiamo a Codex, la CLI di OpenAI. La logica è la stessa di Claude, cambiano i dettagli. Il sottocomando è codex mcp: add per aggiungere, list per elencare, remove per rimuovere; anche qui -- separa il nome del server dal comando da eseguire.

L'esempio Playwright è quasi identico a quello di Claude: stesso pacchetto, stesso npx, cambia solo il comando contenitore. Le variabili d'ambiente si passano con --env (o -e).

• codex mcp add — aggiunge un server.
• codex mcp list — elenca i server (--json per lo script).
• codex mcp remove — rimuove un server.

# Aggiungi Playwright a Codex
codex mcp add playwright -- npx @playwright/mcp@latest

# Elenca e rimuovi
codex mcp list
codex mcp remove playwright

# ...con una variabile d'ambiente
codex mcp add -e API_KEY=*** github -- npx -y github-mcp-server

📄 Codex: il file config.toml

Codex non usa JSON ma TOML. La configurazione vive in ~/.codex/config.toml e ogni server è una tabella dedicata, [mcp_servers.nome]: il nome del server è la parte dopo il punto.

Dentro la tabella metti command e args per un server stdio, e env per le variabili d'ambiente. È l'equivalente esatto del blocco mcpServers di Claude, scritto in TOML invece che in JSON.

⚖️ Claude e Codex a confronto

Le due strade portano allo stesso risultato. Vale la pena tenere a mente le differenze pratiche quando passi dall'uno all'altro: cambia soprattutto dove finisce la configurazione e con che sintassi la scrivi.

✅ Applica e verifica

Il ciclo è sempre lo stesso, su entrambi: aggiungi il server, controlla che risulti connesso, usalo in chat e, se qualcosa non parte, leggi lo stato e i log prima di toccare la configurazione.

Un'ultima accortezza: versiona la configurazione senza segreti. Su Claude condividi .mcp.json, su Codex config.toml, ma i token restano nelle variabili d'ambiente, mai dentro al file.

Altri articoli del blog