OpenCode MCP and ACP: Remote Tools and Editor Setup

OpenCode connects remote MCP servers to the agent and lets code editors talk to that agent through ACP. MCP adds tools and data sources; ACP handles the editor-agent conversation. OAuth is one way to authenticate a remote MCP server; ACP is the protocol editors use to communicate with OpenCode.

Remote MCP with OAuth

In opencode.json (or opencode.jsonc), remote servers use "type": "remote" plus a URL. Headers still work for API keys. For OAuth-capable servers, you can often omit credentials entirely and let OpenCode detect the challenge.

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

When the server returns 401, OpenCode starts the OAuth flow, prefers Dynamic Client Registration (RFC 7591) when the server supports it, and stores tokens under ~/.local/share/opencode/mcp-auth.json. If the prompt does not appear on first use, trigger it yourself:

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

If your provider gives you a client ID, add it under the server’s OAuth settings:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://your-mcp-server.example/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Prefer API keys instead? Set "oauth": false and pass an Authorization header so OpenCode skips auto-detection. If authentication fails, opencode mcp auth list and opencode mcp debug <name> show the authentication status and help diagnose server discovery.

Disable tools you do not need with a tools glob to keep context focused. Enabled MCP tools can add to the prompt context. Our roundup of OpenCode token-tracking plugins covers ways to monitor that usage.

ACP: run OpenCode inside the editor

Agent Client Protocol (ACP) lets editors communicate with coding agents over JSON-RPC. To run OpenCode in an editor, configure it to start:

opencode acp

That process speaks over stdio, so your editor starts it as a child process. If you run opencode acp alone in a terminal, it appears idle while waiting for protocol messages.

Zed can install OpenCode from the ACP registry (zed: acp registry), or you can point settings at a custom binary:

{
  "agent_servers": {
    "OpenCode": {
      "type": "custom",
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

In JetBrains, add an acp.json agent-server entry with the absolute path to opencode and ["acp"] as its arguments, then select OpenCode in the AI Chat agent selector.

Neovim: Avante.nvim uses the same command = "opencode", args = { "acp" } pattern under acp_providers, while CodeCompanion.nvim has an opencode adapter you select in its chat settings. Log in to your provider from a regular terminal with opencode auth login before starting an ACP session.

Inside ACP, OpenCode still loads project config, AGENTS.md, agents, and MCP servers from the session directory. Built-in tools and custom slash commands work. A few TUI-centric commands such as /undo and /redo are called out as unsupported.

ACP-injected HTTP MCP: headers only

Editors can also hand OpenCode MCP servers when a session starts. For HTTP MCP injected that way, OpenCode passes headers through and does not run OAuth for those servers. If you need browser OAuth, configure the remote in your OpenCode config and authenticate with opencode mcp auth first, rather than expecting the ACP handshake to complete the login.

ACP and attach do different things

• opencode acp: Agent Client Protocol agent for editors (stdio / JSON-RPC).
• opencode attach <url>: attach the TUI to a backend you already started with opencode serve or opencode web.

If the editor reports that the process exited or returned invalid protocol output, add --print-logs before acp in the client’s args, so it runs opencode --print-logs acp. Logs go to stderr, leaving stdout available for ACP messages.

• SourceOpenCode docs: MCP servers

• SourceOpenCode docs: ACP support

• SourceOpenCode docs: CLI ACP

• SourceOpenCode docs: CLI

• SourceOpenCode changelog