Shadcn MCP non si connette in Cursor: diagnosi in cinque passi

Risposta breve: il server MCP è un processo figlio dell'editor. Se l'editor non trova npx, non legge il file di configurazione o non ha un progetto valido, la connessione non parte. Esegui il comando a mano: è la diagnosi più veloce.

Come parla un server MCP

Un server MCP locale non apre una porta e non espone un endpoint HTTP: parla su stdin e stdout, in JSON-RPC. L'editor avvia il comando come processo figlio, gli scrive una richiesta di inizializzazione e aspetta la risposta. Se il processo non parte, non scrive nulla o scrive qualcosa che non è JSON-RPC, il pannello MCP resta vuoto. Non c'è un timeout di rete da controllare, perché non c'è rete.

Il punto delicato è che l'editor non usa una shell. Lancia il comando direttamente, con l'ambiente che ha ereditato quando è stato aperto, non quello del tuo terminale. Su Windows npx è uno shim .cmd e non un eseguibile, quindi la chiamata diretta fallisce con ENOENT; su macOS un editor avviato dal Dock non legge il PATH di .zshrc. Sono due facce dello stesso problema: il processo figlio non vede ciò che vedi tu.

Cinque passi, in ordine

1. Apri il terminale nella root del progetto e lancia il comando del server: se non parte lì, non partirà nell'editor.
2. Controlla di essere nella cartella che contiene components.json.
3. Apri il file di configurazione MCP dell'editor e verifica la sintassi JSON.
4. Su Windows, invoca cmd /c npx invece di npx.
5. Riavvia l'editor per intero, non solo la finestra.

Configurazione tipica

{
  "mcpServers": {
    "shadcn": {
      "command": "cmd /c npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Su macOS e Linux il campo command è npx e args resta lo stesso. Il percorso del file dipende dall'editor: alcuni leggono una configurazione globale, altri una nella cartella del progetto. Se esistono entrambe, prevale quella del progetto.

Il passo diagnostico

# run the exact command from the editor config, in the project root
npx shadcn@latest mcp

# the server must stay open and print nothing on stdout:
# that stream carries JSON-RPC only, diagnostics go to stderr

Se il comando resta aperto senza output, il server funziona e il problema è nella configurazione dell'editor. Se stampa un errore e termina, hai la causa in chiaro: copiala. Se parte e chiude subito, manca il progetto. Il dettaglio che inganna è che un server sano è silenzioso: l'assenza di output sembra un blocco, mentre è il comportamento corretto di un trasporto stdio.

Come leggere l'errore

Quando la correzione non funziona

Se il server parte ma non vede i componenti, il progetto potrebbe usare un percorso diverso da quello atteso: apri la cartella che contiene components.json, non la cartella superiore del monorepo. Un secondo limite è il permesso: alcuni editor richiedono l'approvazione esplicita dei tool MCP prima di eseguirli, e senza approvazione il server sembra connesso ma non risponde.

Quando la correzione comune peggiora le cose

La correzione rapida è scrivere nel file di configurazione il percorso assoluto trovato in terminale. Funziona su quella macchina e rompe il repository: il collega su macOS eredita un C:\Program Files\nodejs\npx.cmd che non esiste, e il file versionato diventa la causa del prossimo bug. Lo stesso vale per cmd /c npx copiato in un repository condiviso, e per l'aggiunta di -y con @latest: ogni avvio risolve la versione in rete, quindi dietro un proxy lento il primo handshake supera il timeout dell'editor e il server sembra rotto mentre sta solo scaricando.

Un limite con un nome

Limite dichiarato del trasporto stdio: il server eredita l'ambiente dell'editor e non quello della tua shell. Una variabile esportata in .zshrc o impostata con $env: in PowerShell non arriva al processo figlio, quindi un registry privato che richiede un token si connette e poi rifiuta ogni richiesta. La variabile va dichiarata nel blocco env della configurazione MCP, dove l'editor la passa al processo, e quel blocco non va versionato con il segreto dentro.

Come prevenirlo

• Tieni la configurazione MCP nel repository quando è specifica del progetto.
• Documenta la versione di Node richiesta: il server segue le release di shadcn.
• Concedi solo i tool necessari: un server MCP può leggere e proporre modifiche al progetto.
• Verifica la configurazione con lo stesso comando che usa l'editor, non con uno simile.

Dove continuare

Nel catalogo: componenti, blocchi con preview e icone. Le guide: MCP con shadcn in Claude Code, Cursor e VS Code e registry privati e token; il confronto: copy-paste o headless.