OpenCode MCP: add, configure, and debug MCP servers.

To add an MCP server to OpenCode, run opencode mcp add and follow the prompts, or opencode mcp add <name> --url <url> for a remote server. OpenCode stores servers under the mcp key in opencode.json, each with "type": "local" or "type": "remote". Run opencode mcp list to see if they connect.

Book a demo

Here to connect OpenCode to a database? Read Connect OpenCode to your database, or jump to the worked example.

CLI

The opencode mcp commands.

Checked against OpenCode 1.19.5. The one-line form only covers remote servers. For a local server, use the interactive prompt or edit the config file.

opencode mcp add Interactive. Asks whether to save to this project's opencode.json or your global config, then for the server details.
opencode mcp add <name> --url <url> Add a remote server in one line. Writes to the global config.
opencode mcp add <name> --url <url> --header KEY=VALUE Same, with an HTTP header such as an API key. Repeat --header for more.
opencode mcp list Every configured server with its status, and the error if it failed to connect. Alias: opencode mcp ls.
opencode mcp auth <name> Run the OAuth login for a remote server.
opencode mcp logout <name> Remove stored OAuth credentials for a server.
opencode mcp debug <name> Diagnose OAuth and connection problems for one server.
Terminal 
$ opencode mcp add valv-desktop --url http://127.0.0.1:4319/mcp
◆  MCP server "valv-desktop" added to ~/.config/opencode/opencode.jsonc

# status of every server, with the error if one fails
$ opencode mcp list

Configure MCP servers in opencode.json.

Each server is one entry under mcp. The type key decides the rest: a local server needs a command array, a remote one needs a url. JSON and JSONC (with comments) both work.

Local server

opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "environment": {
        "MY_ENV_VAR": "{env:MY_ENV_VAR}"
      },
      "enabled": true
    }
  }
}

Remote servers

opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "internal-api": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:INTERNAL_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 60000
    }
  }
}

Global or per project.

~/.config/opencode/opencode.json applies everywhere. An opencode.json at a project's root adds servers for that project. OpenCode merges the two instead of picking one, so a project can add a server or override a single key.

Secrets and OAuth.

Write {env:NAME} instead of a token and OpenCode fills it in from your environment, so the file can go in git. Remote servers that answer 401 get an OAuth login. Run opencode mcp auth <name> to start it, or set "oauth": false for API-key servers.

Reference

The mcp keys you'll use.

All of these go inside one server's entry. The OpenCode MCP docs cover the OAuth options in more detail.

Key For What it does
type Both "local" for a server OpenCode starts as a process, "remote" for a URL. Required.
command local The command and its arguments as one array, e.g. ["npx", "-y", "pkg"]. Required for local.
environment local Environment variables for the server process.
cwd local Working directory the server starts in.
url remote The server endpoint. Required for remote.
headers remote HTTP headers sent with every request.
oauth remote OAuth settings (clientId, clientSecret, scope), or false to turn off OAuth detection for API-key servers.
enabled Both Set false to keep a server in the file without starting it.
timeout Both Milliseconds OpenCode waits for the server. The 1.19 source falls back to 30000.

OpenCode's newest config schema also describes a nested form, "mcp": { "servers": { ... } }, and marks the flat form above as deprecated. OpenCode 1.19.5 reads both, and opencode mcp add still writes the flat form, so that's what this page uses.

Converting an mcpServers block from another client.

Most MCP servers document their setup as a Claude Desktop or Cursor snippet. OpenCode uses a different shape, and pasting the snippet as is either does nothing or fails validation. Change these parts.

Claude Desktop, Cursor OpenCode
"mcpServers": { ... } "mcp": { ... }
"command": "npx", "args": ["-y", "pkg"] "command": ["npx", "-y", "pkg"]
"env": { ... } "environment": { ... }
no type, or "stdio" "type": "local"
"type": "http" or "sse" "type": "remote"

Tool names get the server prefix.

OpenCode names each MCP tool <server>_<tool>, with anything other than letters, digits, - and _ replaced by _. That's the name to use when you turn tools off.

Turning tools off.

Add the tool name with false to the top-level tools key. Globs work, so "sentry*": false hides a whole server. An agent's own tools block can turn them back on for that agent only.

When an MCP server doesn't work in OpenCode.

Start with opencode mcp list. It shows config errors first, then each server's status and the reason it failed. The first three messages below are what OpenCode 1.19.5 prints.

No MCP servers configured OpenCode didn't find an mcp key. A block copied from Claude Desktop or Cursor uses mcpServers, which OpenCode ignores without an error. Rename it to mcp and convert each entry (see the table above).
Configuration is invalid ... Expected { readonly "type": "local", ... } An entry under mcp has no type, or still uses command plus args. Add "type": "local" and merge command and args into one array.
SSE error: ECONNREFUSED: Unable to connect Nothing is listening at that URL. Start the server, or fix the host and port. opencode mcp list prints this per server.
Remote server asks for a login, or returns 401 OpenCode tries OAuth when a server answers 401. Run opencode mcp auth <name>. If the server uses an API key instead, send it in headers and set "oauth": false.
A local server times out on the first start The first npx or uvx run downloads the package. Raise timeout for that server, or install the package first.
The server works in one repo but not another It's in that project's opencode.json. Move it to ~/.config/opencode/opencode.json to use it everywhere. Both files are merged, with the project winning on conflicts.
Valv: connection refused on 127.0.0.1:4319 Valv Desktop isn't open, or it picked another port because 4319 was taken. Check the URL in Settings, MCP Server.
Valv: OpenCode sees the wrong data, or none The server answers for the workspace that is active in Valv. Switch to the workspace that holds your database. With no workspace open, it answers 503.

Worked example

Connect OpenCode to a database through Valv's MCP server.

Valv Desktop runs a local MCP server while the app is open. It holds the database connection, so OpenCode only gets a URL and read-only tools, never the password.

  1. 1

    Add your database in Valv.

    Connect Postgres, MySQL, SQLite, ClickHouse, MongoDB, or a folder of Excel and CSV files. Hide any table or column OpenCode shouldn't see in the AI access tab.

  2. 2

    Add the server to OpenCode.

    Port 4319 is the default. If it's taken, Valv uses another port, so check the URL in Settings, MCP Server. Valv's "Other MCP clients" snippet uses mcpServers, so use this command instead. 

    opencode mcp add valv-desktop --url http://127.0.0.1:4319/mcp
  3. 3

    Check what OpenCode saved.

    One remote entry in your global config. No header or token is needed for a local agent. 

    // ~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "valv-desktop": {
      "type": "remote",
      "url": "http://127.0.0.1:4319/mcp"
    }
  }
}
  4. 4

    Ask in OpenCode.

    Keep Valv open and start opencode. It works against whichever workspace is active in Valv, and reads Valv's server instructions on how to use the tools.

Tools OpenCode gets from Valv

valv-desktop_list_datasources

Databases and remote MCP servers in the active workspace.

valv-desktop_list_resources · _describe_resource

Tables and their columns, minus anything hidden in AI access.

valv-desktop_query

A structured, read-only query that Valv validates before it runs.

valv-desktop_run_code

Several read queries chained in one step.

valv-desktop_remember

Proposes a fact for workspace memory. You confirm it in Valv.

valv-desktop_read_file · _write_file · _edit_file

Dashboards and other files in the workspace folder.

valv-desktop_run_flow · _set_flow_enabled · _notify

Test and turn on scheduled checks, send a notification.

With more than one datasource, data tools get a prefix such as app__query. Remote MCP servers connected in Valv, like PostHog, come through with their own prefix.

opencode 
> Which features did accounts that churned last month stop using?

tool  valv-desktop_list_datasources
tool  valv-desktop_describe_resource   events
tool  valv-desktop_query               account_id, feature, created_at

A short table per feature, with the query
object in each tool call.

> Turn this into a dashboard I can open in Valv.

An illustration of the flow, not a recorded session. Tool names and columns depend on your schema. The second prompt has OpenCode write a dashboard file into the Valv workspace.

Only want answers, no files?

The file tools write dashboards into the Valv workspace, not to the database. If you'd rather OpenCode didn't, turn them off. 

{
  "mcp": {
    "valv-desktop": { "type": "remote", "url": "http://127.0.0.1:4319/mcp" }
  },
  "tools": {
    "valv-desktop_write_file": false,
    "valv-desktop_edit_file": false
  }
}

You can also skip the config and run OpenCode inside Valv, with tables and charts next to the chat. Valv then sets up the MCP connection itself. That setup is in Connect OpenCode to your database.

Which MCP server to add for what.

Valv is one option for data. It isn't the right pick for everything.

Library docs

Context7 gives OpenCode current documentation for the libraries in your project. One local entry, as in the example above.

Raw SQL and tuning

If OpenCode should run EXPLAIN, suggest indexes, or write migrations, a standalone database server fits better. Valv doesn't run raw SQL. The Postgres MCP guide compares the options.

Read-only data answers

Valv, when OpenCode should answer questions from your databases without write access or your password. Using another agent too? See the database MCP guide or the Codex MCP guide.

OpenCode MCP, answered

How do I add an MCP server to OpenCode?

Run opencode mcp add for an interactive setup, or opencode mcp add <name> --url <url> for a remote server in one line. You can also add an entry under the mcp key in opencode.json, with "type": "local" and a command array, or "type": "remote" and a url. Check it with opencode mcp list.

Where is the OpenCode MCP config file?

Global servers live in ~/.config/opencode/opencode.json (or opencode.jsonc). Project servers go in opencode.json at the project root. OpenCode merges both, and the project file wins on conflicting keys. opencode mcp add with --url writes to the global file; without flags it asks which one.

Can I paste a Claude Desktop or Cursor mcpServers block into OpenCode?

Not as is. OpenCode ignores mcpServers. Put servers under mcp, add "type": "local" or "remote", merge command and args into one command array, and rename env to environment.

How do I disable an MCP tool in OpenCode?

MCP tools are named <server>_<tool>, so a tool called query on a server called valv-desktop becomes valv-desktop_query. Turn tools off in the tools key, for example "valv-desktop_write_file": false, or "valv-desktop*": false for the whole server. To keep a server configured but stopped, set "enabled": false on it.

How do I keep API keys out of opencode.json?

Use {env:VAR_NAME} in any value, such as "Authorization": "Bearer {env:MY_TOKEN}". OpenCode replaces it with the environment variable when it loads the config. {file:path} reads a value from a file.

Can OpenCode query my database over MCP?

Yes. With Valv Desktop open, run opencode mcp add valv-desktop --url http://127.0.0.1:4319/mcp. OpenCode can then list, describe, and query the tables in Valv's active workspace with read-only tools, and it never receives your database password.

Give OpenCode your database over MCP.

Free for personal use, every feature included. Commercial use needs a seat at beta pricing. See pricing.

All downloads Other platforms and builds