# OpenCode MCP: add a remote MCP server with OAuth

> Add a remote MCP server to OpenCode: opencode.json config, automatic OAuth, opencode mcp list and debug, and per-agent tool limits.

Source: https://datatomcp.com/guides/opencode-mcp · By Killian · Updated 2026-10-27

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:

```json
{
  "$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:

| Field | What it does |
|---|---|
| `enabled` | `false` keeps the server configured but off at startup |
| `headers` | Headers sent with every request, for token-based servers |
| `oauth` | Pre-registered OAuth client details, or `false` to turn OAuth off |
| `timeout` | Request timeout in ms, tool calls included (default 30000) |

## 2. Sign in

```bash
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:

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

## 3. Check it worked

```bash
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

```bash
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:

```json
{
  "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](https://app.datatomcp.com/login), 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](/guides/google-sheets-mcp-server).

## 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](/guides/add-remote-mcp-server) · [Codex](/guides/codex-mcp) · [Claude Code](/guides/claude-code-mcp)