Configurazione OpenCode MCP: 7 passaggi per server locali e remoti

Questa guida copre un intento specifico: aggiungere, autenticare, verificare, limitare e risolvere problemi MCP. Installazione generale, Ollama e sessioni restano in pagine separate per evitare cannibalizzazione.

Gli esempi seguono schema e comandi ufficiali attuali. Il fornitore può cambiare URL, pacchetto, scope o autenticazione: verifica la documentazione originale e non eseguire pacchetti sconosciuti in repository sensibili.

Un server locale è un processo figlio avviato da OpenCode. È adatto a pacchetti CLI affidabili e accesso ai file locali. Runtime, package manager, directory, ambiente e permessi ne determinano l'affidabilità.

Un server remoto è un endpoint HTTP utile per documentazione, monitoraggio o database condivisi. Introduce però dipendenze da rete e autenticazione. Scegli il trasporto supportato ufficialmente.

OpenCode unisce le fonti di configurazione. Gli strumenti comuni vanno nel file globale e quelli del repository in opencode.json. I segreti restano nell'ambiente o in OAuth, mai in Git.

Assegna nomi stabili e descrittivi. Vengono usati in prompt, prefissi e regole per agente. enabled: false documenta un'integrazione opzionale senza caricarla sempre.

Una voce locale richiede type: "local" e un array command. Controlla autore e sorgente, fissa la versione quando serve stabilità e prova fuori da directory sensibili.

Passa i token con environment. Inizia con sola lettura e account di sviluppo. Lo strumento mantiene tutti i privilegi del token anche se il modello sembra prudente.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs_search": {
      "type": "local",
      "command": ["npx", "-y", "trusted-mcp-package"],
      "enabled": true,
      "environment": { "MCP_TOKEN": "{env:MCP_TOKEN}" }
    }
  }
}

Sostituisci il pacchetto fittizio solo con il comando ufficiale del proprietario.

Una voce remota richiede type: "remote" e HTTPS. Usa headers solo secondo il provider. OAuth può partire automaticamente oppure con opencode mcp auth <server-name>.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "monitoring": {
      "type": "remote",
      "url": "https://provider.example/mcp",
      "oauth": {}
    }
  }
}

Controlla opencode mcp list e usa opencode mcp debug <server-name> per connessione o OAuth. Poi esegui una query in sola lettura e confrontala con la fonte.

Registra nome, pacchetto o URL, runtime, autenticazione, prefisso, prompt di prova, timeout e rollback. Così l'esperimento diventa riproducibile.

1. Verificare il providerUsare pacchetto, endpoint e accesso ufficiali.
2. Scegliere ambitoGlobale, progetto o agente specializzato.
3. Aggiungere una voceAttivare un server nuovo per volta.
4. Proteggere i segretiAmbiente o OAuth, mai Git.
5. Elencare e diagnosticareControllare stato, rete e OAuth.
6. Provare in letturaConfrontare con la fonte.
7. Concedere scritturaSolo dopo log, diff e rollback.

opencode mcp list
opencode mcp auth <server-name>
opencode mcp debug <server-name>
opencode mcp logout <server-name>

Le descrizioni degli strumenti occupano contesto. Disattiva server ampi e limitane l'uso all'agente specializzato. Confronta qualità e token prima e dopo.

Prima di condividere log o credenziali, consulta la guida a sessioni e privacy di OpenCode e leggi la guida OpenCode Ollama se gli MCP lavorano con un modello locale dal contesto ridotto.

Risolvi per livelli: processo o endpoint, autenticazione, scoperta OpenCode e infine prompt o policy. Cambiare più livelli nasconde la causa.

Per Figma o Supabase segui prima l'installazione ufficiale del fornitore e poi questa checklist. Un JSON generico può ignorare progetto, regione e autorizzazioni.

In un team tratta l'MCP come una dipendenza: registra versione o endpoint, scope, runtime, responsabile degli aggiornamenti e procedura di revoca. Dopo ogni upgrade ripeti la query in sola lettura e verifica che nomi e parametri degli strumenti siano ancora compatibili prima di riabilitare le operazioni di scrittura.

Per l'installazione di base torna alla guida alla distribuzione OpenCode. Precedenza e opzioni ufficiali sono nelle fonti.