How to Add MCP Servers to OpenCode

Steps

1. 01

   Install OpenCode

   If you have not installed OpenCode yet, pick one of the three official methods. The curl installer is the quickest single-step option:

   # Option 1 — curl installer (recommended for a quick start)
   curl -fsSL https://opencode.ai/install | bash
   
   # Option 2 — npm global install
   npm i -g opencode-ai
   
   # Option 3 — Homebrew (macOS/Linux)
   brew install anomalyco/tap/opencode
   
   # Verify the install
   opencode --version

2. 02

   Configure at least one AI provider

   OpenCode stores your API keys locally and supports 75+ providers. Before MCP tools are useful, the agent needs a model to act on their output. Run the login subcommand and follow the prompts to add your first provider:

   opencode auth login
   # alias:
   opencode providers login

3. 03

   Add an MCP server with opencode mcp add

   Run the add command with a name you choose for the server. For a remote HTTP MCP server, pass the URL with --url and any required HTTP headers with --header. For a local server that needs environment variables, pass them with --env. If you omit these flags, OpenCode will prompt you interactively. The name you give here is what you will use later in auth, logout, and debug commands. Examples (per-server exact URLs and required headers must be confirmed in each server's own docs):

   # Remote HTTP MCP server with an auth header
   opencode mcp add github --url https://mcp.example.com/github --header Authorization="Bearer <token>"
   
   # Remote server with no extra headers
   opencode mcp add context7 --url https://mcp.context7.com
   
   # Local stdio server with an environment variable
   opencode mcp add myserver --env API_KEY=your_key_here
   
   # Interactive (OpenCode prompts for details)
   opencode mcp add myserver

4. 04

   Verify the server is listed and its status

   After adding a server, confirm it registered correctly and check its reported status. The list command (alias: ls) shows every configured MCP server:

   opencode mcp list
   # or the shorter alias:
   opencode mcp ls

5. 05

   Authenticate an OAuth-enabled MCP server

   Some MCP servers (such as official GitHub or Atlassian servers) use OAuth rather than a static API key. After adding the server with mcp add, run mcp auth with the same name you used. OpenCode opens a browser flow and stores the credential locally:

   opencode mcp auth github

6. 06

   Remove OAuth credentials with mcp logout

   To revoke stored OAuth credentials for a server — for example, to switch accounts or rotate access — run mcp logout with the server name. This removes the saved OAuth token but does not delete the server's configuration entry; the server remains registered and will still appear in opencode mcp list:

   opencode mcp logout github

7. 07

   Debug an OAuth connection with mcp debug

   If a server authenticated but tools are still not appearing, the debug command prints diagnostic information about the OAuth connection for that server. This is the first place to look when auth appears to succeed but the agent cannot see tools:

   opencode mcp debug github

8. 08

   Start OpenCode and confirm tools are available

   Launch the TUI. Once inside a session, the agent should list available tools from your connected MCP servers when you ask it what it can do. If you prefer headless usage, opencode run executes a single task:

   # Interactive TUI
   opencode
   
   # Headless single-task
   opencode run "list the open issues in this repo using GitHub MCP"

Troubleshooting

Tools from a connected server do not appear in the session

Run opencode mcp list to check the server status. If it shows an error, re-run opencode mcp add with the correct flags: --url for a remote server, --header for HTTP headers, --env for environment variables needed by a local server. If the server uses OAuth, run opencode mcp auth <name> to complete authentication, then opencode mcp debug <name> to confirm the token is valid. Also check that the server process itself starts correctly outside of OpenCode by running its command directly in a terminal.

opencode mcp auth opens a browser but the callback fails

Ensure your browser can reach localhost on the redirect port the server expects. Some OAuth servers require the redirect URI to be registered in their developer console — confirm on the server's own docs. After a failed flow, run opencode mcp logout <name> to clear any partial OAuth credential (note: this clears the token only, not the server config), then retry opencode mcp auth <name>.

Agent performance degrades after adding several MCP servers

Connecting more than 5–7 MCP servers sends a very long tool list to the model, which can degrade agent performance. Remove servers you are not actively using. The opencode mcp list command shows all configured servers; there is currently no disable-without-delete command, so remove unused entries and re-add them when needed.

opencode: command not found after npm install

The npm global bin directory may not be on your PATH. Run npm prefix -g to find the global prefix directory (e.g. /opt/homebrew or /usr/local); the bin directory is that path plus /bin. Add it to your shell profile: export PATH="$(npm prefix -g)/bin:$PATH" Then reload your shell (source ~/.zshrc or source ~/.bashrc). Alternatively, use the curl installer or Homebrew method, which place the binary in a standard location.

MCP server added but opencode mcp list shows it as disconnected on every launch

Check that the server's transport command (the binary or npx invocation) is available on PATH at the time OpenCode launches. If the server is an npm package, install it globally (npm i -g <package>) rather than relying on npx at runtime, which can fail when network access is restricted or the package version changes.