Skip to content
AgentAtlas

OpenCode MCP Server Setup: Local and Remote Servers in opencode.json

How do I add an MCP server to OpenCode?

Add the server under the top-level mcp key in opencode.json or opencode.jsonc. Use type local with a command array for servers you run yourself, or type remote with a url for hosted servers. Manage OAuth and check connections with the opencode mcp commands.

Compare: add an MCP server in every AI coding agent →

Where MCP servers are configured

OpenCode reads MCP servers from the mcp key in your OpenCode config file, opencode.json or opencode.jsonc. Each server gets a unique name. The global config lives at ~/.config/opencode/opencode.json.

Add a local server

A local server needs type set to local and a command array. Optional keys are cwd, environment, enabled and timeout. The timeout is in milliseconds and defaults to 5000.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": { "MY_ENV_VAR": "value" }
    }
  }
}

Add a remote server

A remote server needs type set to remote and a url. You can send headers, such as an API key. Set oauth to false to turn off OAuth detection for API key servers.

opencode.json

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

OAuth servers

The oauth object accepts clientId, clientSecret and scope. If you leave out clientId, OpenCode tries dynamic client registration. Values can come from environment variables with the {env:NAME} syntax.

opencode.json

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Terminal

opencode mcp auth my-oauth-server
opencode mcp list
opencode mcp debug my-oauth-server
opencode mcp logout my-oauth-server

Turn MCP tools on or off

MCP tools are prefixed with the server name. Disable them with glob patterns in the top-level tools key, then turn them back on for one agent only.

opencode.json

{
  "mcp": {
    "my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true }
  },
  "tools": { "my-mcp*": false },
  "agent": {
    "my-agent": { "tools": { "my-mcp*": true } }
  }
}

Sources

More OpenCode guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →