GuidesHosting choices

MCP servers in OpenCode 2: add, sign in and configure

Add local and remote MCP servers in OpenCode 2 with opencode mcp add, sign in over SSH with no browser, turn tools off, and move a version 1 config.

November 14, 2026The Everpod team
The short answer

In OpenCode 2, MCP servers live under mcp.servers in opencode.json, each one "type": "local" with a command OpenCode starts, or "type": "remote" with a url. The quickest way in is opencode mcp add, run in the project that should use the server: a command after -- for a local one, --url for a remote one, --global for every project. opencode mcp list checks the connection, opencode mcp auth signs in to a server that uses OAuth, and opencode mcp logout forgets the sign-in. Version 2 renamed the keys version 1 used, so a config copied from an older tutorial may need changing. This page describes OpenCode 2.3.0, released November 13, 2026.

# a local server, started by OpenCode over stdio
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything

# a remote server over HTTP, in every project
opencode mcp add name --global --url https://api.example.com/mcp

opencode mcp list          # each server and whether it connected
opencode mcp auth name     # OAuth sign-in for a remote server
opencode mcp logout name   # remove the stored sign-in
Copied

The four commands

On 2.3.0, opencode mcp has exactly four subcommands: list, add, auth and logout. There is no remove: to drop a server, delete its entry from the project or global config where it was added. Without --global, add writes the server to the project you run it in; with it, the server is available everywhere. The global file is ~/.config/opencode/opencode.json, and a project’s sits at its root or in .opencode/ (the config page has the order in which they win). Inside a session, /mcps views, connects, disconnects and signs in to servers; disconnecting there leaves the config as it was.

A local server

“A local server is a command that OpenCode starts over the MCP stdio transport,” in the MCP servers page’s words. Environment variables go on the command as repeated --env NAME=value flags, before the --. In the config file the same server reads:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
        "cwd": ".",
        "environment": {
          "LOG_LEVEL": "info",
          "MCP_API_KEY": "{env:MCP_API_KEY}"
        }
      }
    }
  }
}
Copied

command is the program and its arguments as a list, environment adds variables to the ones OpenCode already has, and a relative cwd resolves from the workspace, which is also the default. The server used here is the MCP project’s test server, which “attempts to exercise all the features of the MCP protocol,” handy for checking a setup before you add a real one.

Note the {env:MCP_API_KEY} form. OpenCode substitutes {env:NAME} from its environment, and “Shell expressions such as $NAME are not expanded in JSON strings,” so a $ reference is sent as the literal text. On version 2 the environment that counts is the background service’s, the one process per user account that runs your sessions: a variable exported in a shell after the service started does not reach it. The OpenCode install guide shows how to set one with opencode service set env.

A remote server, with a key

“A remote server uses the MCP Streamable HTTP transport and requires an absolute URL.” A server that takes a key in a header gets the header in config, with the key read from the environment and OAuth switched off:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "name": {
        "type": "remote",
        "url": "https://api.example.com/mcp",
        "oauth": false,
        "headers": { "Authorization": "Bearer {env:MY_KEY}" }
      }
    }
  }
}
Copied

On the command line, opencode mcp add takes --header 'NAME={env:VAR}' for the same thing, in single quotes so the shell passes the reference through as written. Written this way, the config file holds only the variable’s name, so it can go into a repository. Claude Code and Codex handle the same key differently, one writing the header into its own file and the other reading a named variable; connecting Claude Code and Codex to a remote MCP server sets the two side by side.

OAuth, on a machine with no browser

“OAuth is enabled for remote servers unless oauth is false.” A server that needs a sign-in shows needs authentication in opencode mcp list, and opencode mcp auth name starts it (with no name, it offers the servers that can sign in). Usually nothing needs configuring: OpenCode identifies itself to the server or registers a client and reuses it on later sign-ins. A server that needs a client you registered yourself takes client_id and client_secret inside an oauth object on its entry.

Over SSH, the sign-in finishes in a browser on your own machine, and that browser then tries to return to a callback on the server’s 127.0.0.1, which it cannot reach. The docs cover this case: the browser “shows a page that does not load. Copy that page’s URL from the address bar and paste it into the sign-in prompt.” The URL looks like http://127.0.0.1:52817/callback?code=…&state=…, and the prompt waits for it in opencode mcp auth and in /mcps. Credentials are stored outside the project’s config, per server name, so the same name in two projects shares a sign-in. opencode mcp logout name removes it, for a fresh sign-in or another account.

When a remote server shows as failed

In 2.x, a remote server that fails to connect once stays failed for as long as the background service runs; an open issue reports that it “is never retried while the service keeps running,” whatever made the first attempt fail. Pick the server in /mcps and retry it, or restart the service with opencode service restart.

Turning servers and tools off, and per agent

“Servers connect automatically.” To keep one configured but unconnected, set "disabled": true on its entry; version 2 has no enabled field. To keep the server connected but stop the agent using some of its tools, use permissions: an MCP tool’s name is <server>_<tool>, normalised, and a rule on that name hides or denies it. This denies every tool of a server called name:

{
  "permissions": [
    { "action": "name_*", "resource": "*", "effect": "deny" }
  ]
}
Copied

There is no per-agent list of servers. What OpenCode offers instead is per-agent permissions, which refine the global ones and follow the same rule as everywhere: “The last matching rule wins.” So denying name_* globally and allowing it in one agent’s permissions, in opencode.json under agents or in that agent’s Markdown file in .opencode/agents/, should leave the server’s tools to that agent alone; the agents page has the format, though it does not show this case. Permissions are a guard rail, not a wall: OpenCode’s security policy says the permission system “is not designed to provide security isolation,” and lists MCP servers as “outside our trust boundary.” A server you add runs with your rights, if local, or sees what your agent sends it, if remote.

How many tools, and Code Mode

“MCP tools consume model context, so add only the servers you need.” Version 2 softens this by default with Code Mode: rather than adding every tool to the model’s tool list, it groups a server’s tools under the server’s name, called from code as tools.name.tool_name(…), and adds a line telling the agent where to find them. A server whose tools must sit on the model provider’s native tool list gets "codemode": false on its entry. The docs give no figure for how much context a tool costs either way.

Timeouts

Each server takes a timeout object with three values, in milliseconds: startup, 30 seconds by default, for connecting and starting; catalog, 30 seconds, for listing tools, prompts and resources; and execution, 12 hours, for tool calls and reads. A slow server that times out while starting needs startup raised; a tool that runs long is already covered.

A version 1 MCP config in version 2

Most MCP instructions online were written for version 1, where servers sat directly under mcp. Version 2 “groups servers under mcp.servers, replaces enabled with the inverse disabled, and separates timeout purposes,” according to its migration page:

// version 1
"mcp": {
  "playwright": { "type": "local", "command": ["npx", "@playwright/mcp"], "enabled": true, "timeout": 30000 }
}

// version 2
"mcp": {
  "servers": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp"],
      "disabled": false,
      "timeout": { "catalog": 30000, "execution": 30000 }
    }
  }
}
Copied

OAuth fields moved to snake case, clientId to client_id and clientSecret to client_secret. Version 2 still reads a version 1 file, converting it in memory without rewriting it, and warns only about what it cannot convert, such as an enabled-only version 1 entry with no type, which it ignores. Plugins are the exception that does not carry over: version 1 plugins do not run in version 2, as the guide to OpenCode plugins explains, and Pi against OpenCode covers how the other open-source agent handles MCP.

Run OpenCode on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.