--- title: Server MCP description: Aggiungi strumenti MCP locali e remoti. --- Puoi aggiungere strumenti esterni a OpenCode usando il _Model Context Protocol_, o MCP. OpenCode supporta sia server locali sia remoti. Una volta aggiunti, gli strumenti MCP sono automaticamente disponibili all'LLM insieme agli strumenti integrati. --- #### Avvertenze Quando usi un server MCP, aggiunge contenuto al contesto. Questo puo' crescere rapidamente se hai molti strumenti. Per questo consigliamo di fare attenzione a quali server MCP abiliti. :::tip I server MCP aumentano il contesto, quindi e' meglio essere prudenti su quali abilitare. ::: Alcuni server MCP, come il server MCP di GitHub, tendono ad aggiungere molti token e possono facilmente superare il limite di contesto. --- ## Abilita Puoi definire server MCP nella tua [OpenCode Config](https://opencode.ai/docs/config/) sotto `mcp`. Aggiungi ogni MCP con un nome univoco. Puoi riferirti a quell'MCP per nome quando fai prompt all'LLM. ```jsonc title="opencode.jsonc" {6} { "$schema": "https://opencode.ai/config.json", "mcp": { "name-of-mcp-server": { // ... "enabled": true, }, "name-of-other-mcp-server": { // ... }, }, } ``` Puoi anche disabilitare un server impostando `enabled` a `false`. E' utile se vuoi disabilitare temporaneamente un server senza rimuoverlo dalla configurazione. --- ### Sovrascrivere i default remoti Le organizzazioni possono fornire server MCP predefiniti tramite l'endpoint `.well-known/opencode`. Questi server possono essere disabilitati di default, lasciando agli utenti la possibilita' di fare opt-in su quelli necessari. Per abilitare un server specifico dalla configurazione remota dell'organizzazione, aggiungilo alla configurazione locale con `enabled: true`: ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": true } } } ``` I valori della configurazione locale sovrascrivono i default remoti. Vedi [config precedence](/docs/config#precedence-order) per maggiori dettagli. --- ## Locali Aggiungi server MCP locali impostando `type` a `"local"` dentro l'oggetto `mcp`. ```jsonc title="opencode.jsonc" {15} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-local-mcp-server": { "type": "local", // Or ["bun", "x", "my-mcp-command"] "command": ["npx", "-y", "my-mcp-command"], "enabled": true, "environment": { "MY_ENV_VAR": "my_env_var_value", }, }, }, } ``` Il comando e' come viene avviato il server MCP locale. Puoi anche passare un elenco di variabili d'ambiente. Per esempio, ecco come aggiungere il server MCP di test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything). ```jsonc title="opencode.jsonc" { "$schema": "https://opencode.ai/config.json", "mcp": { "mcp_everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], }, }, } ``` E per usarlo posso aggiungere `use the mcp_everything tool` ai miei prompt. ```txt "mcp_everything" use the mcp_everything tool to add the number 3 and 4 ``` --- #### Opzioni Ecco tutte le opzioni per configurare un server MCP locale. | Opzione | Tipo | Richiesto | Descrizione | | ------------- | ------- | --------- | ------------------------------------------------------------------------------------ | | `type` | String | Y | Tipo di connessione del server MCP, deve essere `"local"`. | | `command` | Array | Y | Comando e argomenti per eseguire il server MCP. | | `environment` | Object | | Variabili d'ambiente da impostare quando si esegue il server. | | `enabled` | Boolean | | Abilita o disabilita il server MCP all'avvio. | | `timeout` | Number | | Timeout in ms per recuperare gli strumenti dal server MCP. Default 5000 (5 secondi). | --- ## Remoti Aggiungi server MCP remoti impostando `type` a `"remote"`. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "my-remote-mcp": { "type": "remote", "url": "https://my-mcp-server.com", "enabled": true, "headers": { "Authorization": "Bearer MY_API_KEY" } } } } ``` `url` e' l'URL del server MCP remoto e con l'opzione `headers` puoi passare un elenco di header. --- #### Opzioni | Opzione | Tipo | Richiesto | Descrizione | | --------- | ------- | --------- | ------------------------------------------------------------------------------------ | | `type` | String | Y | Tipo di connessione del server MCP, deve essere `"remote"`. | | `url` | String | Y | URL del server MCP remoto. | | `enabled` | Boolean | | Abilita o disabilita il server MCP all'avvio. | | `headers` | Object | | Header da inviare con la richiesta. | | `oauth` | Object | | Configurazione autenticazione OAuth. Vedi sezione [OAuth](#oauth) sotto. | | `timeout` | Number | | Timeout in ms per recuperare gli strumenti dal server MCP. Default 5000 (5 secondi). | --- ## OAuth OpenCode gestisce automaticamente l'autenticazione OAuth per i server MCP remoti. Quando un server richiede autenticazione, OpenCode: 1. Rileva la risposta 401 e avvia il flusso OAuth 2. Usa **Dynamic Client Registration (RFC 7591)** se supportato dal server 3. Memorizza i token in modo sicuro per richieste future --- ### Automatico Per la maggior parte dei server MCP con OAuth, non serve alcuna configurazione speciale. Basta configurare il server remoto: ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp" } } } ``` Se il server richiede autenticazione, OpenCode ti chiedera' di autenticarti la prima volta che provi a usarlo. In caso contrario, puoi [attivare manualmente il flusso](#authenticating) con `opencode mcp auth `. --- ### Pre-registrato Se hai credenziali client dal provider del server MCP, puoi configurarle: ```json title="opencode.json" {7-11} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": { "clientId": "{env:MY_MCP_CLIENT_ID}", "clientSecret": "{env:MY_MCP_CLIENT_SECRET}", "scope": "tools:read tools:execute" } } } } ``` --- ### Autenticazione Puoi avviare manualmente l'autenticazione o gestire le credenziali. Autentica con un server MCP specifico: ```bash opencode mcp auth my-oauth-server ``` Elenca tutti i server MCP e il loro stato di autenticazione: ```bash opencode mcp list ``` Rimuovi credenziali memorizzate: ```bash opencode mcp logout my-oauth-server ``` Il comando `mcp auth` aprira' il browser per l'autorizzazione. Dopo l'autorizzazione, OpenCode memorizzera' i token in modo sicuro in `~/.local/share/opencode/mcp-auth.json`. --- #### Disabilitare OAuth Se vuoi disabilitare l'OAuth automatico per un server (ad esempio per server che usano API key), imposta `oauth` a `false`: ```json title="opencode.json" {7} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-api-key-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:MY_API_KEY}" } } } } ``` --- #### Opzioni OAuth | Opzione | Tipo | Descrizione | | -------------- | --------------- | --------------------------------------------------------------------------- | | `oauth` | Object \| false | Oggetto config OAuth, o `false` per disabilitare l'auto-detection di OAuth. | | `clientId` | String | OAuth client ID. Se non fornito, si prova la dynamic client registration. | | `clientSecret` | String | OAuth client secret, se richiesto dal server di autorizzazione. | | `scope` | String | Scope OAuth da richiedere durante l'autorizzazione. | #### Debug Se un server MCP remoto non riesce ad autenticarsi, puoi diagnosticare i problemi con: ```bash # View auth status for all OAuth-capable servers opencode mcp auth list # Debug connection and OAuth flow for a specific server opencode mcp debug my-oauth-server ``` Il comando `mcp debug` mostra lo stato di autenticazione corrente, testa la connettivita' HTTP e prova il flusso di discovery OAuth. --- ## Gestione I tuoi MCP sono disponibili come strumenti in OpenCode insieme agli strumenti integrati. Quindi puoi gestirli tramite la configurazione OpenCode come qualunque altro strumento. --- ### Globale Questo significa che puoi abilitarli o disabilitarli globalmente. ```json title="opencode.json" {14} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp-foo": false } } ``` Possiamo anche usare un pattern glob per disabilitare tutti gli MCP corrispondenti. ```json title="opencode.json" {14} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp*": false } } ``` Qui stiamo usando il pattern glob `my-mcp*` per disabilitare tutti gli MCP. --- ### Per agente Se hai molti server MCP, potresti volerli abilitare solo per agente e disabilitarli globalmente. Per farlo: 1. Disabilitalo globalmente come strumento. 2. Nella tua [config dell'agente](/docs/agents#tools), abilita il server MCP come strumento. ```json title="opencode.json" {11, 14-18} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true } }, "tools": { "my-mcp*": false }, "agent": { "my-agent": { "tools": { "my-mcp*": true } } } } ``` --- #### Pattern glob Il pattern glob usa semplici regole di globbing: - `*` corrisponde a zero o piu' caratteri qualsiasi (ad esempio `"my-mcp*"` corrisponde a `my-mcp_search`, `my-mcp_list`, ecc.) - `?` corrisponde esattamente a un carattere - Tutti gli altri caratteri corrispondono letteralmente :::note Gli strumenti del server MCP vengono registrati con il nome del server come prefisso, quindi per disabilitare tutti gli strumenti di un server e' sufficiente usare: ``` "mymcpservername_*": false ``` ::: --- ## Esempi Qui sotto trovi esempi di alcuni server MCP comuni. Puoi inviare una PR se vuoi documentare altri server. --- ### Sentry Aggiungi il [server MCP di Sentry](https://mcp.sentry.dev) per interagire con i tuoi progetti e le issue di Sentry. ```json title="opencode.json" {4-8} { "$schema": "https://opencode.ai/config.json", "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } } ``` Dopo aver aggiunto la configurazione, autentica con Sentry: ```bash opencode mcp auth sentry ``` Questo aprira' una finestra del browser per completare il flusso OAuth e collegare OpenCode al tuo account Sentry. Una volta autenticato, puoi usare gli strumenti Sentry nei tuoi prompt per interrogare issue, progetti e dati sugli errori. ```txt "use sentry" Show me the latest unresolved issues in my project. use sentry ``` --- ### Context7 Aggiungi il [server MCP Context7](https://github.com/upstash/context7) per cercare nella documentazione. ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } } ``` Se ti sei registrato per un account gratuito, puoi usare la tua API key e ottenere rate limit piu' alti. ```json title="opencode.json" {7-9} { "$schema": "https://opencode.ai/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" } } } } ``` Qui assumiamo che tu abbia impostato la variabile d'ambiente `CONTEXT7_API_KEY`. Aggiungi `use context7` ai tuoi prompt per usare il server MCP Context7. ```txt "use context7" Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 ``` In alternativa, puoi aggiungere qualcosa del genere al tuo [AGENTS.md](/docs/rules/). ```md title="AGENTS.md" When you need to search docs, use `context7` tools. ``` --- ### Grep by Vercel Aggiungi il server MCP [Grep by Vercel](https://grep.app) per cercare snippet di codice su GitHub. ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } } ``` Dato che abbiamo chiamato il nostro server MCP `gh_grep`, puoi aggiungere `use the gh_grep tool` ai tuoi prompt per fare in modo che l'agente lo usi. ```txt "use the gh_grep tool" What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool ``` In alternativa, puoi aggiungere qualcosa del genere al tuo [AGENTS.md](/docs/rules/). ```md title="AGENTS.md" If you are unsure how to do something, use `gh_grep` to search code examples from GitHub. ```