All MCP setup guides
MCPOpenCode

How to Add a Remote MCP Server to OpenCode

OpenCode needs type set to remote — its config schema requires it, and an entry without it does not load. Since OpenCode 2 the entry also sits under mcp.servers, not mcp. One config block, automatic OAuth, and the CLI commands that name the problem for you.

Last verified November 4, 2026

How do I add a remote MCP server to OpenCode?

Add a remote entry with "type": "remote" and the server's url to opencode.json — under mcp on OpenCode 1, under mcp.servers on OpenCode 2. OpenCode discovers the OAuth endpoint and registers itself, so your browser opens to the consent screen on first connect and there is nothing to obtain in advance. The "type": "remote" line is not optional — OpenCode's config schema requires both type and url on a remote entry, and remote is the only value it accepts there, so an entry without it does not load.

Which OpenCode do you have?

Run opencode --version first. As of November 2026 two lines are current and their MCP config shapes differ:

  • OpenCode 1 (1.x) is what npm install -g opencode-ai and curl -fsSL https://opencode.ai/install | bash install. Servers go directly under mcp.
  • OpenCode 2 (2.x) ships as @opencode/cli, brew install anomalyco/tap/opencode-v2, or curl -fsSL https://opencode.ai/v2/install | bash. Servers go under mcp.servers, and OpenCode 2 does not read names placed directly under mcp.

The config

OpenCode reads opencode.json (or opencode.jsonc) in your project directory, or ~/.config/opencode/opencode.json for a global setup. OpenCode 2 also accepts .opencode/opencode.json in a project.

OpenCode 1:

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

OpenCode 2:

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

On OpenCode 2 the CLI can write the entry for you — opencode mcp add my-server --url https://mcp.example.com/mcp, with --global to make it available in every project.

Three things to note. The block is mcp, not mcpServers — another client, another vocabulary. "type": "remote" is required on both versions: it is what tells OpenCode this is a hosted server rather than a local command to spawn. OpenCode's published config schema makes the point plainly — a remote entry requires type and url, a local entry requires type and command, and type is the field that decides which shape yours is. Leave it out and the entry matches neither, so the server never loads. And OpenCode 2 uses disabled: true to keep a server configured without connecting it, where OpenCode 1 used enabled: false.

Authorization

Authentication is automatic. OpenCode discovers the server's OAuth endpoint and registers itself — OpenCode 1 through dynamic client registration, OpenCode 2 through a client ID metadata document where the authorization server supports one and dynamic client registration otherwise. When the server asks for authentication, OpenCode prompts you and your browser opens to the consent screen — sign in if prompted and approve.

To authenticate up front rather than on first use:

opencode mcp auth my-server

On OpenCode 2 you can also run /mcps inside OpenCode, select the server, and sign in there.

Verifying, and the commands worth knowing

opencode mcp list
opencode mcp debug my-server

list shows each server's connection status on both versions. debug is OpenCode 1 only: it prints the connection attempt step by step and usually names the problem directly rather than leaving you to infer the failure from a missing tool list. On OpenCode 2, /mcps inside OpenCode is where you view, connect, disconnect, or authenticate servers.

What usually goes wrong

  • Server does not load. Confirm the entry has "type": "remote" and a url, sits at the right level for your version (mcp on OpenCode 1, mcp.servers on OpenCode 2), and that the file is valid JSON. OpenCode's schema requires type on every MCP entry, so an entry without it never loads.
  • Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.
  • Auth errors or expired tokens. Run opencode mcp logout <name> to clear the stored credentials, then opencode mcp auth <name> to redo the OAuth flow. On OpenCode 1, tokens live in ~/.local/share/opencode/mcp-auth.json if you want to see what is stored.
  • Tools not appearing. Start a new OpenCode session after adding the config.
  • Times out fetching tools. OpenCode 1 waits 30 seconds by default to connect and fetch a remote server's tool list (older builds documented 5 seconds), and a slow first response, for example a server waking from idle, can still miss a short window. Raise timeout in milliseconds on the entry — for example "timeout": 60000. OpenCode 2 allows 30 seconds for startup and 30 seconds for listing tools by default, and its timeout is an object — for example "timeout": { "startup": 60000, "catalog": 60000 }.
  • Tools look different on OpenCode 2. Code Mode is the default there: tools are grouped as tools.<server>.<tool>(...). Set "codemode": false on the entry if you want them on the model's native tool list.
  • Not sure what's failing. OpenCode 1: opencode mcp debug <name>. OpenCode 2: opencode mcp list, then /mcps.

Model freedom, and what it means for the config

OpenCode runs 75+ model providers — Claude, GPT, and Gemini alongside open models like GLM, Kimi, Qwen, and DeepSeek, via their own providers, OpenRouter, or local runtimes.

Because MCP lives in the harness rather than the model, you can swap models mid-project and your server connection stays exactly where it was. One configuration covers every provider you use, and changing provider costs you nothing in setup.

A worked example

With a real server — Tempreon, a hosted MCP server that gives your AI a persistent memory of how you work — on OpenCode 2:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "tempreon": {
        "type": "remote",
        "url": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp"
      }
    }
  }
}

On OpenCode 1, drop the servers level and put tempreon directly under mcp, with "enabled": true. Start a session, approve the browser prompt, and opencode mcp list should show it connected. That combination is the practical payoff of the model-freedom point above: a preference the model learns in a GLM session is still there when the next session runs on Claude. The account-holder walkthrough is in the OpenCode setup doc.

Sources

The dated claims on this page were checked against these vendor documents. Client UIs move constantly, so if one of these has changed since the date shown, trust the vendor over this page — and tell us.

Frequently asked questions

I added a server but OpenCode does not load it. What is wrong?
This usually means the entry is missing its remote type, or it is nested at the wrong level for your version. In OpenCode, type set to remote is what tells it the server is hosted rather than a local subprocess, and the config schema requires type on every MCP entry: a remote server needs type set to remote plus a url, and a local one needs type set to local plus a command. On OpenCode 2 the entry must also sit under mcp.servers, because OpenCode 2 does not read server names directly under mcp. Open opencode.json, confirm the entry has type set to remote and a url, sits at the right level, and is valid JSON, then start a new session.
Where do I add an MCP server in OpenCode?
OpenCode reads opencode.json in your project directory, or ~/.config/opencode/opencode.json for a global setup. On OpenCode 1, add an mcp block with an entry whose type is remote and whose url is the server endpoint. On OpenCode 2, put the same entry under mcp.servers, or run opencode mcp add with the server name and --url. Check which you have with opencode --version.
How do I see what's actually failing in an OpenCode MCP connection?
opencode mcp list shows each server's connection status on both versions. On OpenCode 1, opencode mcp debug followed by the server name prints the connection attempt step by step, which usually names the problem directly. OpenCode 2 has no debug subcommand; run /mcps inside OpenCode to view, connect, disconnect, or authenticate a server.