OpenCode MCP: add a remote MCP server with OAuth

By Killian, founder · Updated 27 October 2026 · Markdown

To add a remote MCP server to OpenCode, add an entry with "type": "remote" and the server’s url under mcp in opencode.json. OpenCode starts the OAuth sign-in by itself the first time the server answers 401, or you can run opencode mcp auth <name> to sign in up front. opencode mcp list shows whether it worked. This guide covers the config, header-based servers, the debug command, and keeping tool count under control.

The example server is datatomcp, which lets OpenCode query your CSVs and Google Sheets.

1. Add the server

Put this in opencode.json at the root of a project, or in ~/.config/opencode/opencode.json to have it in every project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "datatomcp": {
      "type": "remote",
      "url": "https://app.datatomcp.com/mcp"
    }
  }
}

opencode mcp add walks you through the same thing interactively if you’d rather not edit JSON.

Remote entries accept a few more fields:

2. Sign in

opencode mcp auth datatomcp

OpenCode registers itself with the server (dynamic client registration), opens your browser, and stores the token in ~/.local/share/opencode/mcp-auth.json. For datatomcp you sign in with your datatomcp account and approve read access to your datasets. If you skip this step, OpenCode starts the same flow the first time it needs the server.

Servers that use an API key

Turn OAuth off and send the key as a header. {env:NAME} reads an environment variable, so the key stays out of the file:

{
  "mcp": {
    "my-api": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:MY_API_TOKEN}" }
    }
  }
}

3. Check it worked

opencode mcp list

Each server shows ✓ connected or ⚠ needs authentication, with its URL. Before signing in, datatomcp shows needs authentication, which is expected. After opencode mcp auth datatomcp it shows connected.

MCP tools are available to the model alongside the built-in ones, prefixed with the server name. Ask:

Use datatomcp to list my datasets, then count orders per country in the orders dataset.

Debugging a server that won’t connect

opencode mcp debug datatomcp

checks the stored token, makes a test request and walks the OAuth discovery without finishing it. Against datatomcp before sign-in, it reports HTTP response: 401 Unauthorized with a WWW-Authenticate header pointing at the server’s OAuth metadata, then confirms a client ID is available. That output means discovery works and only the browser sign-in is missing.

Other fixes:

• Stuck on needs authentication after signing in. Run opencode mcp logout datatomcp, then opencode mcp auth datatomcp again.
• A token-based server keeps opening a browser. Add "oauth": false so OpenCode doesn’t try OAuth.
• Tool calls time out. Raise timeout on that server.
• Context fills up fast. Each server adds its tool descriptions to every request, and large servers can push you over the context limit. Turn off what you don’t need (below).

Limit which agents get a server

Disable a server’s tools globally with a glob, then enable them only for the agent that needs them:

{
  "tools": { "datatomcp_*": false },
  "agent": {
    "analyst": { "tools": { "datatomcp_*": true } }
  }
}

A data server for OpenCode

When a task needs numbers from a spreadsheet (a pricing table, an export, a forecast the finance team keeps in Google Sheets), OpenCode can query it through datatomcp instead of reading the file into context. The tools are read-only: list_datasets, describe_dataset, query_rows, aggregate and distinct_values. Totals are computed by a database over every row, and each answer names the dataset version it used.

Create a free account, add a CSV or Google Sheet under Add data, and paste the config above. For the sheet side, see the Google Sheets MCP server guide.

FAQ

Where does OpenCode look for MCP config? opencode.json (or opencode.jsonc) in the project and ~/.config/opencode/opencode.json globally.

Does OpenCode support OAuth for remote MCP servers? Yes, automatically, with dynamic client registration when the server supports it.

How do I sign out of a server? opencode mcp logout <name>.

More clients: Add a remote MCP server to any AI client · Codex · Claude Code