Server MCP

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.

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 sotto mcp. Aggiungi ogni MCP con un nome univoco. Puoi riferirti a quell’MCP per nome quando fai prompt all’LLM.

{
  "$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:

{
  "$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 per maggiori dettagli.

Locali

Aggiungi server MCP locali impostando type a "local" dentro l’oggetto mcp.

{
  "$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.

{
  "$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.

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".

{
  "$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 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:

Rileva la risposta 401 e avvia il flusso OAuth
Usa Dynamic Client Registration (RFC 7591) se supportato dal server
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:

{
  "$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 con opencode mcp auth <server-name>.

Pre-registrato

Se hai credenziali client dal provider del server MCP, puoi configurarle:

{
  "$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:

opencode mcp auth my-oauth-server

Elenca tutti i server MCP e il loro stato di autenticazione:

opencode mcp list

Rimuovi credenziali memorizzate:

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:

{
  "$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:

# 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.

{
  "$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.

{
  "$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:

Disabilitalo globalmente come strumento.
Nella tua config dell’agente, abilita il server MCP come strumento.

{
  "$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

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 per interagire con i tuoi progetti e le issue di Sentry.

{
  "$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:

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.

Show me the latest unresolved issues in my project. use sentry

Context7

Aggiungi il server MCP Context7 per cercare nella documentazione.

{
  "$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.

{
  "$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.

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.

When you need to search docs, use `context7` tools.

Grep by Vercel

Aggiungi il server MCP Grep by Vercel per cercare snippet di codice su GitHub.

{
  "$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.

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.

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.