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 — 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.

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. 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.

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 does not load. Confirm the entry has "type": "remote" and a url, 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. 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 waits 5000 ms by default for a remote server's tool list, and a slow first response, for example a server waking from idle, can miss that window. Add a timeout in milliseconds to the entry — for example "timeout": 15000.
• 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.