Server MCP

Aggiungi strumenti MCP locali e remoti.

Puoi aggiungere strumenti esterni a OpenCode utilizzando il Model Context Protocol, o MCP. OpenCode supporta sia server locali che remoti.

Una volta aggiunti, gli strumenti MCP sono automaticamente disponibili per il LLM insieme agli strumenti integrati.

Avvertenze

Quando usi un server MCP, aggiunge al contesto. Questo possono sommarsi rapidamente se hai molti strumenti. Quindi raccomandiamo di essere attenti con quali server MCP usi.

Alcuni server MCP, come il server MCP di GitHub, tendono ad aggiungere molti token e possono facilmente superare il limite del contesto.

Abilita

Puoi definire i server MCP nella tua Configurazione OpenCode sotto mcp. Aggiungi ogni MCP con un nome univoco. Puoi fare riferimento a quel MCP per nome quando invii il prompt al 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 su false. Questo e utile se desideri disabilitare temporaneamente un server senza rimuoverlo dalla tua configurazione.

Sostituire i valori predefiniti remoti

Le organizzazioni possono fornire server MCP predefiniti tramite il loro endpoint .well-known/opencode. Questi server potrebbero essere disabilitati per impostazione predefinita, consentendo agli utenti di optare per quelli di cui hanno bisogno.

Per abilitare un server specifico dalla configurazione remota della tua organizzazione, aggiungilo alla tua configurazione locale con enabled: true:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

I tuoi valori di configurazione locale sostituiscono i valori predefiniti remoti. Vedi precedenza di configurazione per maggiori dettagli.

Locale

Aggiungi server MCP locali utilizzando type su "local" nell’oggetto MCP.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Oppure ["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.

Ad esempio, ecco come puoi 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.

Option	Type	Required	Description
`type`	String	Y	Tipo di connessione MCP, deve essere `"local"`.
`command`	Array	Y	Comando e argomenti per eseguire il server MCP.
`environment`	Object		Variabili d’ambiente da impostare durante l’esecuzione del server.
`enabled`	Boolean		Abilitare o disabilitare il server MCP all’avvio.
`timeout`	Number		Timeout in ms per recuperare gli strumenti dal server MCP. Predefinito 5000 (5 secondi).

Remoto

Aggiungi server MCP remoti impostando type su "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"
      }
    }
  }
}

L’url e l’URL del server MCP remoto e con l’opzione headers puoi passare un elenco di intestazioni.

Opzioni

Option	Type	Required	Description
`type`	String	Y	Tipo di connessione MCP, deve essere `"remote"`.
`url`	String	Y	URL del server MCP remoto.
`enabled`	Boolean		Abilitare o disabilitare il server MCP all’avvio.
`headers`	Object		Intestazioni da inviare con la richiesta.
`oauth`	Object		Configurazione di autenticazione OAuth. Vedi sezione OAuth sotto.
`timeout`	Number		Timeout in ms per recuperare gli strumenti dal server MCP. Predefinito 5000 (5 secondi).

OAuth

OpenCode gestisce automaticamente l’autenticazione OAuth per i server MCP remoti. Quando un server richiede l’autenticazione, OpenCode:

Rilevera la risposta 401 e avviera il flusso OAuth
Usara la Registrazione dinamica del client (RFC 7591) se supportata dal server
Archivera i token in modo sicuro per richieste future

Automatico

Per la maggior parte dei server MCP compatibili con OAuth, non e necessaria alcuna configurazione speciale. Configura semplicemente 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 l’autenticazione, OpenCode ti chiedera di autenticarti quando provi a usarlo per la prima volta. 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 attivare manualmente l’autenticazione o gestire le credenziali.

Autenticati 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 le credenziali archiviate:

opencode mcp logout my-oauth-server

Il comando mcp auth aprira il tuo browser per l’autorizzazione. Dopo l’autorizzazione, OpenCode archiviera i token in modo sicuro in ~/.local/share/opencode/mcp-auth.json.

Disabilitare OAuth

Se desideri disabilitare OAuth automatico per un server (ad esempio, per server che usano chiavi API invece), imposta oauth su 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

Option	Type	Description
`oauth`	Object \| false	Oggetto di configurazione OAuth o `false` per disabilitare il riconoscimento automatico OAuth.
`clientId`	String	ID client OAuth. Se non fornito, sara tentata la registrazione dinamica del client.
`clientSecret`	String	Segreto client OAuth, se richiesto dal server di autorizzazione.
`scope`	String	Ambiti OAuth da richiedere durante l’autorizzazione.

Debug

Se un server MCP remoto non riesce ad autenticarsi, puoi diagnosticare i problemi con:

# Vedi lo stato di autenticazione per tutti i server compatibili OAuth
opencode mcp auth list

# Debug connessione e flusso OAuth per un server specifico
opencode mcp debug my-oauth-server

Il comando mcp debug mostra lo stato di autenticazione corrente, testa la connettivita HTTP e tenta il flusso di scoperta OAuth.

Gestire

I tuoi MCP sono disponibili come strumenti in OpenCode, insieme agli strumenti integrati. Quindi puoi gestirli tramite la configurazione OpenCode come qualsiasi 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 i 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 i MCP.

Per agente

Se hai un gran numero di server MCP, potresti volerli abilitare solo per agente e disabilitarli globalmente. Per fare questo:

Disabilitalo come strumento globalmente.
Nella tua configurazione 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 pattern di globbing regex:

* corrisponde a zero o piu caratteri (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

Di seguito sono riportati esempi di alcuni server MCP comuni. Puoi inviare una PR se desideri documentare altri server.

Sentry

Aggiungi il server MCP Sentry per interagire con i tuoi progetti e problemi Sentry.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Dopo aver aggiunto la configurazione, autenticati con Sentry:

opencode mcp auth sentry

Questo aprira una finestra del browser per completare il flusso OAuth e connettere OpenCode al tuo account Sentry.

Una volta autenticato, puoi usare gli strumenti Sentry nei tuoi prompt per interrogare problemi, progetti e dati di errore.

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 chiave API e ottenere limiti di velocita 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 la variabile d’ambiente CONTEXT7_API_KEY impostata.

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

Alternativamente, 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 frammenti di codice su GitHub.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Poiche abbiamo nominato il nostro server MCP gh_grep, puoi aggiungere use the gh_grep tool ai tuoi prompt per far si 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

Alternativamente, 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.