Skip to main content

​
Overview

MCP (Model Context Protocol) servers add external tools to OpenCode. Configure local command-based servers or remote HTTP servers with optional OAuth authentication.

​
Local MCP Server

{
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      },
      "timeout": 5000
    }
  }
}

​
Local Server Options

OptionTypeRequiredDescription
type"local"YesServer type
commandstring[]YesCommand to run
environmentobjectNoEnvironment variables
enabledbooleanNoEnable on startup
timeoutnumberNoTimeout in ms (default: 5000)

​
Remote MCP Server

{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      }
    }
  }
}

​
Remote Server Options

OptionTypeRequiredDescription
type"remote"YesServer type
urlstringYesServer URL
headersobjectNoHTTP headers
oauthobject / falseNoOAuth config or disable
enabledbooleanNoEnable on startup
timeoutnumberNoTimeout in ms (default: 5000)

​
OAuth Configuration

{
  "mcp": {
    "oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MCP_CLIENT_ID}",
        "clientSecret": "{env:MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

​
Per-Agent MCP Tools

Restrict MCP tools to specific agents: 
{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"]
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "researcher": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}
This disables MCP tools globally but enables them only for the researcher agent.

​
Registry Shorthand

In registry component manifests, remote MCP servers use URL shorthand: 
"opencode": {
  "mcp": {
    "context7": "https://mcp.context7.com/mcp"
  }
}
This expands to { "type": "remote", "url": "https://...", "enabled": true }.

​
See Also