How to Add a Remote MCP Server to OpenCode

How do I add a remote MCP server to OpenCode?

Add an mcp block to opencode.json with "type": "remote", the server's url, and "enabled": true. OpenCode discovers the OAuth endpoint and registers itself via dynamic client registration, 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 — without it OpenCode treats the entry as a local subprocess and it never connects.

The config

OpenCode reads opencode.json in your project directory, or ~/.config/opencode/opencode.json for a global setup:

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

Two things to note. The block is mcp, not mcpServers — another client, another vocabulary. And "type": "remote" is required: it is what tells OpenCode this is a hosted server rather than a local command to spawn. An entry without it is not rejected; it is misclassified, which is why the symptom is "ignored" rather than "invalid."

Authorization

Authentication is automatic. OpenCode discovers the server's OAuth endpoint and registers itself via dynamic client registration. The first time it connects, 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

Verifying, and the two commands worth knowing

opencode mcp list
opencode mcp debug my-server

list shows each server's connection status. debug prints the connection attempt step by step and usually names the problem directly.

That second command is why an OpenCode connection is straightforward to troubleshoot: rather than leaving you to infer the failure from a missing tool list, debug usually names the problem directly.

What usually goes wrong

• Server ignored or treated as local. Confirm the entry has "type": "remote" and "enabled": true, and that the file is valid JSON.
• 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 auth <name> to redo the OAuth flow. OpenCode stores tokens in ~/.local/share/opencode/mcp-auth.json; deleting the server's entry there forces a clean re-auth.
• Tools not appearing. Start a new OpenCode session after adding the config — the tool list is read at session start.
• Not sure what's failing. opencode mcp debug <name>.

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:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tempreon": {
      "type": "remote",
      "url": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp",
      "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.