How to add MCP servers to OpenCode

Add MCP servers to OpenCode with opencode mcp add or the mcp section of opencode.json, for one project or every project.

Local servers: Yes; runs stdio servers
Hosted servers: Yes; connects by URL
Config: JSON; how servers are added
Picks: 8; ranked

In OpenCode 2, opencode mcp add <name> --url <address> adds a hosted server to the project, and --global adds it to every project. By hand, servers go under mcp.servers in opencode.json; OpenCode 1 put them directly under mcp, so check which version you run before copying a config. Every server adds to the model's context, so add only the ones you need.

Good for

Developers who want OpenCode to reach docs, a browser, GitHub or their database
Teams that keep shared servers in a project opencode.json in git
People upgrading from OpenCode 1 whose config stopped working
Anyone whose server keeps asking to sign in

Install OpenCode

OpenCode

Copy this prompt.

Add the OpenCode MCP server to OpenCode. Run this command:

curl -fsSL https://opencode.ai/v2/install | bash

Then check that it loaded and tell me if I need to sign in or restart.

2
Paste it into OpenCode. It shows the change and asks before running it.

OpenCode 2 and OpenCode 1 use different MCP config shapes. The OpenCode 1 installers can replace an OpenCode 2 install. OpenCode 2 does not support Windows package managers; download the standalone Windows binary instead.

From the vendor's docs. Source.

At a glance

Add a hosted server: opencode mcp add <name> --url <address> [--global]
Add a local server: opencode mcp add <name> -- <command>
Global config: ~/.config/opencode/opencode.json
Project config: opencode.json or .opencode/opencode.json in the project
Config key (OpenCode 2): mcp.servers.<name>
Config key (OpenCode 1): mcp.<name>
Server types: local (stdio command) or remote (Streamable HTTP URL)
Sign in: /mcps in OpenCode, or opencode mcp auth <name>
Check servers: opencode mcp list
Default timeouts: 30 s startup, 30 s tool list, 12 h tool call

Add an MCP server to OpenCode

1
Add a hosted server from your project folder
```
opencode mcp add context7 --url https://mcp.context7.com/mcp
```
This writes the server to the project config. Add --global to use it in every project. Pass keys with --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}' (keep the single quotes).
Uses Context7
2
Or add a local server by its command
Put the launch command after --, with keys as repeated --env flags:
```
opencode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything
```

Or edit opencode.json by hand

Project: opencode.json (or .opencode/opencode.json) in the project root. Every project: ~/.config/opencode/opencode.json. In OpenCode 2, servers sit under mcp.servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" },
      "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp@latest"] }
    }
  }
}

Use {env:NAME} for secrets; $NAME is not expanded.

Uses Playwright MCP

4
Check the connection
Run opencode mcp list. A working server shows ✓ context7 connected; one that needs sign-in says so.
5
Sign in if it asks
Open OpenCode, type /mcps, select the server and finish the sign-in in your browser. From the shell, opencode mcp auth <name> does the same. opencode mcp logout <name> clears it so you can switch accounts.
6
Use it by name
OpenCode names each tool <server>_<tool>, so short server names keep prompts readable.
Prompt
```
Use context7 to look up the current Astro docs for content collections, then update src/content/config.ts.
```
Uses Context7
7
Turn a server off without deleting it
In OpenCode 2 add "disabled": true to the server. OpenCode 1 uses "enabled": false instead.

Best MCP servers for OpenCode

Official servers with an approved PlugWiki page whose setup for this client is documented by the vendor or client; ordered by GitHub stars, then weekly downloads, then name.

MCP servers that work in OpenCode

40 · official first, then servers with a page, then by stars

Show all 40

Common errors and fixes

Servers from an old config are ignored after upgrading
Cause: OpenCode 2 reads servers under mcp.servers, not directly under mcp.
Fix: Move each server into mcp.servers and change enabled: false to disabled: true.
opencode Source
An env var like $API_KEY is sent as literal text
Cause: OpenCode does not expand shell expressions in JSON strings.
Fix: Write {env:API_KEY} instead.
opencode Source
Server keeps saying it needs authentication
Cause: OAuth is on for remote servers and you have not signed in, or the token expired.
Fix: Run /mcps or opencode mcp auth <name>; for key-only servers set oauth to false and send a header.
opencode Source
Sign-in fails for a remote server
Cause: The authorization server supports neither of the sign-up methods OpenCode tries.
Fix: If the provider gave you client credentials, add them as a pre-registered client with client_id. In OpenCode 1, opencode mcp debug <name> shows where sign-in fails.
opencode Source
Model runs out of context with MCP servers on
Cause: Each server adds its tools to the context, some by a lot.
Fix: Remove unused servers or deny their tools with permissions.
opencode Source
A project server overrides your global one and breaks
Cause: A project entry with the same name replaces the whole server object.
Fix: Use a different name, or repeat every required field in the project entry.
opencode Source

Verdict

OpenCode supports local and hosted MCP servers with automatic sign-in and a simple opencode mcp add command. The main limit is that OpenCode 2 changed the config shape to mcp.servers, so many guides and OpenCode 1 configs no longer work as written.

Best for

Developers who want an open source terminal agent with MCP
People who keep project servers in a committed opencode.json

Skip it if

You are copying an old mcpServers or OpenCode 1 config without converting it
You install on Windows through a package manager, which OpenCode 2 does not support

Questions

How do I add an MCP server to OpenCode?

Run opencode mcp add <name> --url <address> for a hosted server or opencode mcp add <name> -- <command> for a local one, from your project folder. Add --global for every project.

Where is the OpenCode config file?

For every project it is ~/.config/opencode/opencode.json. For one project it is opencode.json or .opencode/opencode.json in the project root, and closer files win. JSONC with comments works too.

What does the OpenCode MCP config look like?

In OpenCode 2, each server is a named entry under mcp.servers with type set to local (plus command) or remote (plus url). OpenCode 1 puts the named entries directly under mcp.

Why did my MCP config stop working after upgrading OpenCode?

OpenCode 2 expects servers under mcp.servers, not directly under mcp, and uses disabled instead of enabled. OAuth fields also changed to snake_case, such as client_id.

How do I sign in to an MCP server in OpenCode?

Type /mcps in OpenCode, pick the server and sign in in your browser, or run opencode mcp auth <name>. Hosted servers try sign-in automatically unless you set oauth to false.

How do I use an API key instead of sign-in?

Set "oauth": false and send the key as a header, for example "Authorization": "Bearer {env:MCP_API_KEY}". Keep the key in an environment variable, not in the file.

Why does an MCP server use so much context in OpenCode?

Every server's tools are sent to the model. OpenCode's docs warn that some, like the GitHub MCP server, add many tokens; add only what you need or deny tools you do not use with permissions.

How long does OpenCode wait for a server?

30 seconds to start and 30 seconds to list tools, and up to 12 hours for a tool call in OpenCode 2. Change them under mcp.timeout or a server's own timeout.

Information

updated Nov 1, 2026

Transports: stdio, Streamable HTTP
Config file (all): opencode.json (mcp)
MCP docs: opencode.ai

Docs

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

Intro (OpenCode 2) · opencode.ai
Intro (OpenCode 1) · opencode.ai
MCP servers (OpenCode 2) · opencode.ai
MCP servers (OpenCode 1) · opencode.ai
Config (OpenCode 2) · opencode.ai