YouTipOpencode Mcp
MCP (Model Context Protocol) is an open protocol that allows you to connect external tools and data sources to OpenCode. After adding an MCP server, its provided tools will automatically appear alongside OpenCode's built-in tools, and the LLM can invoke them directly during conversations.
OpenCode supports two types of MCP servers:
* **Local**: MCP processes launched via command line on your machine, suitable for local tools and scripts
* **Remote**: Remote MCP services connected via HTTPS, suitable for cloud services and third-party platforms
> **Context consumption reminder:** Each MCP server consumes conversation context space. The more tools you enable, the more tokens are consumed per conversation, and the more likely you are to hit the model's context limit. It is recommended to only enable MCP servers actually needed for the current task, and disable them when done. Some servers (such as GitHub MCP) have a large number of tools, and token consumption is especially significant—please use with extra caution.
* * *
## Basic Configuration Structure
All MCP server configurations are written under the `mcp` field in `opencode.json`. Each server requires a **unique name** as the key, which can also be used in prompts to specify which MCP to invoke:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp-server": { // Server name (custom, globally unique)
"type": "local", // Connection type: local or remote
// ...other configuration items
"enabled": true // Whether enabled, default is true
},
"another-mcp-server": { // Multiple MCP servers can be configured simultaneously
"type": "remote",
// ...
}
}
}
Setting `enabled` to `false` can temporarily disable a server without removing it from the configuration file, making it easy to toggle on demand:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": false // Temporarily disabled, configuration retained, change back to true when needed next time
}
}
}
* * *
## Local MCP Servers
Local MCP servers provide tools by running a command process on your machine. Set `type` to `"local"`, and specify the startup command via `command`:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-local-mcp-server": {
"type": "local", // Connection type: local
"command": ["npx", "-y", "my-mcp-command"], // Startup command array:
// First element is the executable,
// subsequent elements are arguments
// Can also be written as ["bun", "x", "my-mcp-command"]
"enabled": true,
"environment": { // Environment variables injected at runtime (optional)
"MY_ENV_VAR": "my_env_var_value"
}
}
}
}
### Local Server Configuration Items
| Configuration Item | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | String | Yes | Connection type, local servers must fill in `"local"` |
| `command` | Array | Yes | Command and arguments to start the MCP server, in array form, e.g. `["npx", "-y", "my-mcp"]` |
| `environment` | Object | No | Environment variables injected when running the server, in key-value pairs |
| `enabled` | Boolean | No | Whether to enable this server at startup, default is `true` |
| `timeout` | Number | No | Timeout for retrieving tool list from MCP server (milliseconds), default is `5000` (5 seconds) |
### Example: Adding a Test MCP Server
Below is an example of adding the official test MCP server `@modelcontextprotocol/server-everything`, which can be used to verify whether MCP functionality is working properly:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp_everything": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
// npx -y means auto-confirm installation, no need to manually npm install
}
}
}
After configuration is complete, include the server name in the prompt to let the LLM invoke that MCP's tools:
use the mcp_everything tool to add the number 3 and 4
* * *
## Remote MCP Servers
Remote MCP servers connect to cloud services via HTTPS. Set `type` to `"remote"`, and specify the server address via `url`:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-mcp": {
"type": "remote", // Connection type: remote
"url": "https://my-mcp-server.com", // Remote server address (required)
"enabled": true,
"headers": { // HTTP headers sent with requests (optional)
"Authorization": "Bearer MY_API_KEY" // Commonly used for API key authentication
}
}
}
}
### Remote Server Configuration Items
| Configuration Item | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | String | Yes | Connection type, remote servers must fill in `"remote"` |
| `url` | String | Yes | Complete HTTPS address of the remote MCP server |
| `enabled` | Boolean | No | Whether to enable this server at startup, default is `true` |
| `headers` | Object | No | HTTP headers sent with each request, commonly used for API key authentication |
| `oauth` | Object / `false` | No | OAuth authentication configuration, or set to `false` to disable automatic OAuth detection |
| `timeout` | Number | No | Timeout for retrieving tool list from MCP server (milliseconds), default is `5000` (5 seconds) |
### Referencing Environment Variables
In the configuration file, **do not write sensitive information such as API keys in plain text**. OpenCode supports reading system environment variables at runtime via the `{env:VARIABLE_NAME}` syntax:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com",
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}" // Automatically reads the value of environment variable MY_API_KEY at runtime
// Need to set this environment variable in the system beforehand:
// export MY_API_KEY=your_actual_key
}
}
}
}
* * *
## OAuth Authentication
OpenCode has built-in support for OAuth authentication for remote MCP servers, and the entire process is almost fully automatic, requiring no manual token handling.
### Automatic Authentication Flow
When a server requires OAuth authentication, OpenCode will automatically complete the following steps:
1. Detect that the server returns a 401 (Unauthorized) response
2. Automatically launch the OAuth authorization flow, opening the browser to guide you through login
3. Use dynamic client registration (RFC 7591) to automatically register the application when supported by the server
4. Securely store the obtained token in `~/.local/share/opencode/mcp-auth.json`
5. Automatically carry the token in subsequent requests, no need to repeat login
### 1. Automatic OAuth (No Additional Configuration Required)
For most MCP servers that support OAuth, simply configure `url` and OpenCode will automatically guide you through authentication on first use:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-oauth-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp"
// No additional configuration needed, OpenCode automatically handles the OAuth flow
}
}
}
You can also manually trigger the authentication flow (for example, to re-login after token expiration):
```bash
opencode mcp auth my-oauth-server
### 2. Pre-registered Client Credentials
If you have already obtained fixed client ID and secret from the service provider, you can specify them directly in the configuration to skip the dynamic registration step:
## Example
```json
{
"$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}", // Read from environment variable to avoid exposing in plain text
"clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
"scope": "tools:read tools:execute" // Requested permission scope, specific values determined by service provider
}
}
}
}
### 3. Disabling OAuth (Using API Key Authentication)
If the server uses API key authentication instead of OAuth, you can set `oauth` to `false` to disable automatic OAuth detection, and use `headers` to pass the key:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-api-key-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": false, // Disable automatic OAuth detection
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}" // Directly use API key for authentication
}
}
}
}
### OAuth Configuration Items
| Configuration Item | Type | Description |
| --- | --- | --- |
| `oauth` | Object / `false` | OAuth configuration object; set to `false` to completely disable automatic OAuth detection |
| `clientId` | String | OAuth client ID. If not provided, OpenCode will attempt dynamic client registration |
| `clientSecret` | String | OAuth client secret (if required by the authorization server) |
| `scope` | String | Permission scope requested during authorization, multiple permissions separated by spaces, specific values determined by service provider |
### Authentication Management Commands
OpenCode provides a set of command-line tools for managing MCP authentication status:
```bash
# Authenticate with a specified MCP server (will open browser to complete OAuth authorization)
opencode mcp auth my-oauth-server
# List all configured MCP servers and their current authentication status
opencode mcp list
# Delete stored credentials for a specified server (will need to re-login on next use)
opencode mcp logout my-oauth-server
# Debug a specified server's connection and OAuth flow (displays authentication status, tests connection, executes OAuth discovery flow)
opencode mcp debug my-oauth-server
# View authentication status of all OAuth-supported servers
opencode mcp auth list
* * *
## Overriding Remote Default Configuration
Organizations can provide pre-configured MCP server configurations for members via the `.well-known/opencode` endpoint; these servers may be disabled by default. If you need to enable one of them, simply add an entry with the same name in your local configuration and set `enabled: true`. **Local configuration will override remote defaults**:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jira": { // Must match the server name in the organization's remote configuration
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": true // Set to true locally to override the remote default disabled state
}
}
}
* * *
## Tool Management
After MCP servers are registered, their tools will appear in OpenCode's tool list in the form of `serverName_toolName`, and can be managed uniformly via the `tools` field.
### 1. Globally Disabling Specified MCP Tools
## Example
```json
{
"$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 // Disable all tools from my-mcp-foo server (server will still start, but tools are unavailable)
}
}
### 2. Batch Disabling Using Glob Patterns
Glob wildcards can be used to match and disable tools from multiple MCP servers at once:
## Example
```json
{
"$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 // Glob pattern: disable tools from all servers whose names start with my-mcp
}
}
### 3. Enabling Specific MCP Tools by Agent
If you have configured a large number of MCP servers but each agent only needs some of them, you can first globally disable all MCP tools, then enable them as needed in specific agent configurations. This allows precise control over which tools each agent can access, avoiding context waste:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-mcp": {
"type": "local",
"command": ["bun", "x", "my-mcp-command"],
"enabled": true // Server itself remains started (otherwise agents cannot use it either)
}
},
"tools": {
"my-mcp*": false // Step 1: Globally disable all tools from this MCP, unavailable in default conversations
},
"agent": {
"my-agent": {
"tools": {
"my-mcp*": true // Step 2: Only enable in my-agent agent, other agents are unaffected
}
}
}
}
### Glob Pattern Rules
| Wildcard | Meaning | Example |
| --- | --- | --- |
| `*` | Matches zero or more of any characters | `my-mcp*` matches `my-mcp_search`, `my-mcp_list`, etc. |
| `?` | Matches exactly one arbitrary character | `my-mcp?` matches `my-mcpA`, but not `my-mcpAB` |
| Other characters | Matched literally as exact match | `my-mcp-foo` only matches servers with exactly that name |
> When MCP server tools are registered, they are prefixed with the server name. For example, tools from server `myserver` are registered as `myserver_toolname`. Therefore, to disable all tools from a server, use `"myserver_*": false` for precise matching.
* * *
## Configuration Examples
### Sentry
Adding the Sentry MCP server allows you to directly query Sentry project errors, issues, and event data in conversations:
## Example
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sentry": {
"type": "remote",
"url": "https://sentry.example.com/mcp"
}
}
}