MCP setup guide

OpenCode

OpenCode V2 connects to remote MCP servers over Streamable HTTP and exposes their tools, prompts, and resources in the terminal, editor, and desktop app. The native CLI writes project config by default and can target the global config with --global.

Paths checked against the client's docs · November 2026

Surfaces

TUI · IDE · Desktop

Scope

Project or global

Project configopencode.jsonc
Installer agentopencode
1 / How it works

How OpenCode handles MCP

OpenCode V2 connects to remote MCP servers over Streamable HTTP and exposes their tools, prompts, and resources in the terminal, editor, and desktop app. The native CLI writes project config by default and can target the global config with --global.

Project or global. Project scope keeps the server with the repository; global scope makes it available in every workspace.

Best for

People who want one native MCP setup across the terminal and editor.

Installer flag-a opencode
2 / Where it goes

Where the MCP config lives

The installer writes this file for you. Use the paths below when you want to inspect, edit, or remove a server by hand.

Project
opencode.jsonc

or .opencode/opencode.json(c); V2 nests servers under mcp.servers

Global
~/.config/opencode/opencode.jsonc

Project paths are relative to the workspace. Global paths are per user. On Windows, ~ means your user folder; use %USERPROFILE% in Explorer or PowerShell. A project config is shared with the team; a global config is personal.

3 / Install

Add a remote server

Start with a server in the MCP directory, or use your provider's endpoint. The examples use https://mcp.example.com/mcp so you can see the shape; replace it with the real URL.

  1. 01

    Find the endpoint

    Open a server page and copy its hosted endpoint. Do not use a local command or an npm package name for a remote server; those are different connection types.

    Open the MCP directory
  2. 02

    Run the installer

    OpenCode V2 writes project config by default. Add --global for every project. The server name becomes example in the config.

    OpenCode · project
    opencode mcp add example --url https://mcp.example.com/mcp
    OpenCode · global
    opencode mcp add example --url https://mcp.example.com/mcp --global

    OpenCode V2 remote servers use Streamable HTTP. If the endpoint is SSE-only, use an HTTP endpoint or a local bridge instead of this command.

    Windows Terminal showing the native opencode mcp add command in a project folder and the path to the saved opencode.json file.Open larger view
    The native command runs in your project folder and writes the remote server to that project's opencode.json file.View full size

    The command prints the saved config path and returns to the prompt.

    If no path appears, run the command from your project folder and confirm OpenCode is installed.

    Full screenshot
    Windows Terminal showing the native opencode mcp add command in a project folder and the path to the saved opencode.json file.
    VS Code with opencode.json open. The file defines a remote Context7 server under mcp.servers.Open larger view
    The OpenCode project config. The server entry sits under mcp.servers in OpenCode V2.View full size

    The server name, type, and URL are present under mcp.servers.

    If the file is missing, you are in the wrong folder or the command did not finish.

    Full screenshot
    VS Code with opencode.json open. The file defines a remote Context7 server under mcp.servers.
  3. 03

    Authorize if the provider asks

    The first connection may open a browser for OAuth. Sign in with the provider and approve only the scopes you need. If the server uses an API key, create it in the provider's dashboard and add it through the client's auth flow or config.

    Never paste a provider token into a project config you will commit. Prefer the client's secret store or a user-level config for credentials.

  4. 04

    Reload and verify

    Run `opencode` in the project folder, open `/mcps`, and confirm the new server. A remote server can show Sign in required until authentication finishes.

    OpenCode MCP servers list showing the added cloudflare-code-mode server with Sign in required.Open larger view
    Run opencode in your project folder, then open /mcps. The MCP server you added appears in this list. When OpenCode asks for credentials, sign in to connect it before using its tools.View full size

    The added server appears in /mcps and can be selected.

    If it is missing, start a new session from the same project folder and reload /mcps.

    Full screenshot
    OpenCode MCP servers list showing the added cloudflare-code-mode server with Sign in required.

    Then ask for a task, not a tool: “Find the open issues assigned to me” or “Summarize the latest release.” The client decides which advertised tool to call.

4 / Use

What changes in the chat

Once the server is connected, its tools appear in the client's tool list. You still talk to the agent normally; MCP is plumbing, not a different chat interface.

Read

“Find the customer notes mentioning the migration and summarize the blockers.”

Write

“Create a draft page with this outline, but do not publish it yet.”

Investigate

“Check the failed deployment and list the last three changes that touched it.”

Verify

“Which MCP tools do you have available for this task?”

If the agent ignores the server, check that the server is enabled and that its tools are approved. Some clients require a per-tool confirmation before the first call.

5 / Troubleshooting

When it does not connect

The server is missing

Confirm the file exists at the path above, the JSON or TOML is valid, and you restarted the client or opened a new session.

It connects but tools are empty

Enable the server in the client's MCP UI, approve its tools, and check that the provider has not revoked your token.

OAuth keeps reopening

Remove the server from the client, revoke the app's access in the provider's account settings, then add it again.

A project server is ignored

Some clients require you to trust the folder before loading project MCP config. Trust the repository, then start a new session.

6 / Notes

What to watch for in OpenCode

  • V2 nests servers under `mcp.servers`; do not copy a V1 config that puts server names directly under `mcp`.
  • `opencode mcp add <name> --url <endpoint>` writes the project config. Add `--global` to write the user config instead.
  • Remote servers use OAuth by default. Run `/mcps` or `opencode mcp auth <name>` to sign in, and `opencode mcp logout <name>` to clear credentials.
  • OpenCode V2 remote servers use Streamable HTTP. SSE-only endpoints need an HTTP endpoint or a local bridge.
7 / Remove

Remove or reset the server

Remove the server when it is no longer needed, or reset it when a credential or connection state gets stuck.

  1. Delete the server entry under mcp.servers in opencode.jsonc or the global OpenCode config.
  2. Run opencode mcp logout <name> to clear stored OAuth credentials for that server.
  3. Start a new OpenCode session and open /mcps to confirm it is gone.

If authentication is stuck, remove the server entry, run `opencode mcp logout <name>`, and add it again.

Sources

Official documentation

Client behavior changes. These links are the source of truth for paths, flags, and approval behavior.

Next setup guideClaude Code