Opencode Mcp

OpenCode MCP Servers

> 📚 Official Docs: For the latest information, always refer to the official documentation: > https://opencode.ai/docs/mcp-servers/

Add local and remote MCP tools to OpenCode using the Model Context Protocol (MCP). MCP is a standard protocol that lets you connect external tool servers to AI applications. OpenCode supports both local servers (child processes) and remote servers (HTTP). Once added, MCP tools are automatically available to the LLM alongside OpenCode's built-in tools.

---

Context Caveat

When you use an MCP server, it adds tokens to the context. Every tool the MCP server exposes is described in the context window, which consumes tokens. This can quickly add up if you have a lot of tools from multiple MCP servers. Be careful with which MCP servers you enable.

• Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
• Each additional MCP server multiplies the tool definitions injected into context.
• Monitor your context window usage and be selective about which servers you enable.

---

Enable / Disable

MCP servers are defined in your OpenCode Config (opencode.json or opencode.jsonc) under the mcp key. Each server gets a unique name used to reference it in prompts and tool management.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ... server config ...
      "enabled": true
    },
    "name-of-other-mcp-server": {
      // ... server config ...
    }
  }
}

• Set "enabled": true to explicitly enable a server.
• Set "enabled": false to temporarily disable a server without removing its config.
• If enabled is omitted, the server is enabled by default.

---

Local MCP Servers

Local servers run as child processes on your machine. Use "type": "local" with a command array.

Full Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      },
      "timeout": 5000
    }
  }
}

Options

| Option | Type | Required | Description | |---|---|---|---| | type | String | Yes | Must be "local". | | command | Array | Yes | Command and arguments to run the MCP server. Use an array, e.g. ["npx", "-y", "package-name"] or ["bun", "x", "my-mcp-command"]. | | environment | Object | No | Environment variables to set when running the server process. | | enabled | Boolean | No | Enable or disable the MCP server on startup. Defaults to true. | | timeout | Number | No | Timeout in milliseconds for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |

Example: @modelcontextprotocol/server-everything

The test server from the MCP project — useful for verifying your setup works:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Then reference it in your prompts:

use the mcp_everything tool to add the number 3 and 4

Example: Filesystem Server

Grants the LLM read/write access to specified directories on your filesystem:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

The path argument (/Users/me/projects) restricts the server to only that directory.

Example: GitHub MCP Server

Provides access to GitHub repositories, issues, pull requests, and more:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Warning: The GitHub MCP server adds many tool definitions to context and can easily consume a large portion of your context budget. Consider disabling it globally and enabling it per-agent when needed.

Running with Bun

If you use Bun instead of Node.js:

{
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    }
  }
}

---

Remote MCP Servers

Remote servers connect over HTTP. Use "type": "remote" with a url.

Full Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      },
      "oauth": {},
      "timeout": 5000
    }
  }
}

Options

| Option | Type | Required | Description | |---|---|---|---| | type | String | Yes | Must be "remote". | | url | String | Yes | URL of the remote MCP server. | | enabled | Boolean | No | Enable or disable the MCP server on startup. | | headers | Object | No | HTTP headers to send with requests (e.g., API keys, custom headers). | | oauth | Object \| false | No | OAuth authentication configuration. See [OAuth](#oauth-authentication) section. Set to false to disable auto-detection. | | timeout | Number | No | Timeout in milliseconds for fetching tools. Defaults to 5000 (5 seconds). |

Using Environment Variables in Headers

Reference environment variables with the {env:VAR_NAME} syntax:

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

This avoids hardcoding secrets in your config file.

---

OAuth Authentication

OpenCode automatically handles OAuth for remote MCP servers. When a server requires authentication, OpenCode:

1. Detects the 401 response from the server.
2. Initiates the OAuth flow using Dynamic Client Registration (RFC 7591) if the server supports it.
3. Opens your browser for the user to authorize.
4. Stores tokens securely for future requests.

Automatic OAuth

For most OAuth-enabled servers, no special configuration is needed. Just configure the remote server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

If the server requires authentication, OpenCode will prompt you to authenticate when you first try to use it. You can also manually trigger the flow:

opencode mcp auth my-oauth-server

Pre-registered Credentials

If you have client credentials from the MCP server provider (i.e., you already registered your app), configure them directly:

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

When clientId and clientSecret are provided, OpenCode skips Dynamic Client Registration and uses the pre-registered credentials directly.

OAuth Options

| Option | Type | Description | |---|---|---| | oauth | Object \| false | OAuth config object, or false to disable OAuth auto-detection entirely. | | clientId | String | OAuth client ID. If omitted, Dynamic Client Registration will be attempted. | | clientSecret | String | OAuth client secret, if required by the authorization server. | | scope | String | OAuth scopes to request during authorization (space-separated). |

CLI Commands

OpenCode provides several CLI commands for managing MCP authentication:

# Manually authenticate with a specific server
opencode mcp auth my-oauth-server

# List all MCP servers and their auth/connection status
opencode mcp list

# Remove stored credentials for a server
opencode mcp logout my-oauth-server

# Debug connection and OAuth flow for a specific server
opencode mcp debug my-oauth-server

opencode mcp add

Interactive wizard to add a new MCP server to your configuration. Guides you through choosing local or remote, setting the command or URL, and other options.

opencode mcp auth

Opens your browser to complete the OAuth authorization flow. After you authorize, OpenCode stores the tokens.

opencode mcp list

Shows all configured MCP servers, their type (local/remote), enabled status, and authentication status.

opencode mcp logout

Removes stored OAuth tokens for the specified server. You will need to re-authenticate on next use.

opencode mcp debug

Shows the current auth status, tests HTTP connectivity to the server, and attempts the OAuth discovery flow. Useful for diagnosing connection and authentication issues.

Token Storage

OAuth tokens are stored locally at:

~/.local/share/opencode/mcp-auth.json

This file is managed automatically by OpenCode. Do not edit it manually.

Disabling OAuth

If a server uses API keys instead of OAuth, disable automatic OAuth detection to prevent unnecessary 401-based OAuth flows:

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

---

Tool Management

MCP tools are registered alongside built-in tools. Each MCP tool is named with the pattern:

_

For example, if your MCP server is named "github" and it exposes a tool called search_repos, the tool appears as github_search_repos in OpenCode.

Global Enable / Disable

Disable specific MCP tools via the tools config:

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

In this example, all tools from my-mcp-foo are disabled, while my-mcp-bar tools remain active.

Glob Patterns

Use glob patterns to disable all matching tools at once:

{
  "tools": {
    "my-mcp*": false
  }
}

Glob syntax:

• * — matches zero or more of any character (e.g., "my-mcp*" matches my-mcp_search, my-mcp_list, my-mcp_fetch, etc.)
• ? — matches exactly one character
• All other characters match literally

Since MCP server tools are registered with the server name as a prefix, to disable all tools for a specific server:

{
  "tools": {
    "mymcpservername_*": false
  }
}

Per-Agent Enable / Disable

If you have many MCP servers, you may want to disable them globally and enable them selectively per agent. This keeps the default context lean while allowing specific agents to use the tools they need.

Step 1: Disable the MCP tools globally:

{
  "tools": {
    "my-mcp*": false
  }
}

Step 2: Enable them per agent in the agent config:

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

Now my-mcp tools are only available to my-agent. Other agents won't see these tools in their context.

MCP Servers in Agent Permissions

MCP tool names follow the same permission model as built-in tools. You can grant or revoke MCP tools in agent permission configs using the same tools key with glob patterns.

---

Overriding Remote Defaults

Organizations can provide default MCP servers via their .well-known/opencode endpoint. These servers may be disabled by default, allowing users to opt-in to the ones they need.

To enable a specific server from your organization's remote config, add it to your local config with "enabled": true:

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

Local config values override remote defaults. If the organization's remote config defines jira with "enabled": false, your local "enabled": true takes precedence. See config precedence for more details.

---

Complete Examples

Sentry (Remote + OAuth)

Add the Sentry MCP server to interact with your Sentry projects and issues.

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

After adding the configuration, authenticate:

opencode mcp auth sentry

This opens a browser window to complete the OAuth flow. Once authenticated, use Sentry tools in your prompts:

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

Context7 (Remote + API Key Header)

Add the Context7 MCP server to search through documentation.

Without API key (free tier, rate-limited):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

With API key (higher rate limits):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Assumes the CONTEXT7_API_KEY environment variable is set.

Add use context7 to your prompts:

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

Or add to your AGENTS.md:

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

Grep by Vercel (Remote)

Add the Grep by Vercel MCP server to search through public code snippets on GitHub.

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

Reference it in prompts with 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

Or add to your AGENTS.md:

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

Filesystem (Local)

Grants the LLM read/write access to specified directories:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

The path argument restricts filesystem access to the specified directory only.

GitHub MCP (Local)

Provides access to GitHub repos, issues, pull requests, and more:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Context warning: The GitHub MCP server exposes many tools and adds a l

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timmy6942025
• Source: Timmy6942025/opencode-builder-skill
• License: MIT

Install and usage instructions live in the source repository linked above.