Add a remote MCP server to OpenCode
OpenCode lists MCP servers under mcp in its config, and a remote server is type "remote" with a url. It has its own variable syntax and tries OAuth on its own unless you tell it not to.
By Jake Marsh. Checked against OpenCode's own docs on 2026-10-31; each section links its source.
The OpenCode config
For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: opencode.json in the project root, or ~/.config/opencode/opencode.json for every project.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Swap in your own server below and the OpenCode version updates first, with every other client after it.
Where OpenCode reads it
~/.config/opencode/opencode.jsonglobal: every projectopencode.json in the project root (found by walking up to the nearest Git directory)project: overrides global keys that conflict; the files are merged, not replaced
Source: opencode.ai/docs/config/
Keys, headers and sign-in
Put a static key in headers. OpenCode substitutes {env:VAR} with an environment variable (empty when unset) and {file:path} with a file's contents, so neither the key nor its file has to live in the config.
When a server answers 401, OpenCode starts OAuth, using dynamic client registration when the server supports it. For a server that takes an API key, set "oauth": false so it doesn't. opencode mcp auth <name> signs in by hand.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer {env:MY_SERVER_KEY}" }
}
}
}Source: opencode.ai/docs/mcp-servers/
Check that it connected
opencode mcp list shows each server and its sign-in status, and opencode mcp debug <name> diagnoses connection and OAuth problems.
Source: opencode.ai/docs/mcp-servers/
OpenCode gotchas
The variable syntax is {env:VAR}, without the $ other clients use. A ${VAR} copied from another config isn't substituted.
Source: opencode.ai/docs/config/
The timeout defaults to 30,000 ms for connecting and fetching tools. Set timeout (in ms) on the entry for a slow server.
Source: opencode.ai/docs/mcp-servers/
Every MCP server adds to the context, which adds up with many tools. Tools are prefixed with the server name, so "my-server_*": false under tools turns off a whole server's tools, and an agent can turn them back on.
Source: opencode.ai/docs/mcp-servers/
Still not connecting? OpenCode MCP server not connecting walks through the fixes in order.
Generate the config for your server
Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.
OpenCode
opencode.json in the project root, or ~/.config/opencode/opencode.json for every project
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: opencode.ai/docs/mcp-servers/
Claude Code
Run in a terminal (--scope user makes it available in every project)
claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"Source: code.claude.com/docs/en/mcp
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: cursor.com/docs/context/mcp
Codex CLI
~/.codex/config.toml
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Source: developers.openai.com/codex/mcp
Windsurf / Devin Desktop
~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Devin CLI / Devin Local
Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)
devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"VS Code (Copilot agent mode)
.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)
{
"servers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: code.visualstudio.com/docs/agents/reference/mcp-configuration
Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in the project)
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Antigravity CLI (agy)
~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: antigravity.google/docs/mcp
Cline
cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)
{
"mcpServers": {
"my-server": {
"type": "streamableHttp",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: docs.cline.bot/mcp/mcp-overview
Need a task list for those agents?
Taskhold is a remote MCP server that gives OpenCode and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.