OpenCode MCP Server Setup: Local and Remote Servers in opencode.json
How do I add an MCP server to OpenCode?
Add the server under the top-level mcp key in opencode.json or opencode.jsonc. Use type local with a command array for servers you run yourself, or type remote with a url for hosted servers. Manage OAuth and check connections with the opencode mcp commands.
Compare: add an MCP server in every AI coding agent →
Where MCP servers are configured
OpenCode reads MCP servers from the mcp key in your OpenCode config file, opencode.json or opencode.jsonc. Each server gets a unique name. The global config lives at ~/.config/opencode/opencode.json.
Add a local server
A local server needs type set to local and a command array. Optional keys are cwd, environment, enabled and timeout. The timeout is in milliseconds and defaults to 5000.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-local-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true,
"environment": { "MY_ENV_VAR": "value" }
}
}
}Add a remote server
A remote server needs type set to remote and a url. You can send headers, such as an API key. Set oauth to false to turn off OAuth detection for API key servers.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-server": {
"type": "remote",
"url": "https://my-mcp-server.com",
"enabled": true,
"headers": { "Authorization": "Bearer MY_API_KEY" }
}
}
}OAuth servers
The oauth object accepts clientId, clientSecret and scope. If you leave out clientId, OpenCode tries dynamic client registration. Values can come from environment variables with the {env:NAME} syntax.
opencode.json
{
"mcp": {
"my-oauth-server": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "{env:MY_MCP_CLIENT_ID}",
"clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
"scope": "tools:read tools:execute"
}
}
}
}Terminal
opencode mcp auth my-oauth-server opencode mcp list opencode mcp debug my-oauth-server opencode mcp logout my-oauth-server
Turn MCP tools on or off
MCP tools are prefixed with the server name. Disable them with glob patterns in the top-level tools key, then turn them back on for one agent only.
opencode.json
{
"mcp": {
"my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true }
},
"tools": { "my-mcp*": false },
"agent": {
"my-agent": { "tools": { "my-mcp*": true } }
}
}Sources
More OpenCode guides
Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →