Configuring MCP Servers

OpenCode supports Model Context Protocol (MCP) for adding external tools. Both local and remote servers are supported. Once added, MCP tools are automatically available to the LLM alongside built-in tools.

Local Server

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["bunx", "@playwright/mcp"]
      }
    }
  }
}

Remote Server

{
  "mcp": {
    "servers": {
      "remote-api": {
        "type": "remote",
        "url": "https://api.example.com/mcp"
      }
    }
  }
}

OAuth for Remote Servers

{
  "mcp": {
    "servers": {
      "oauth-server": {
        "type": "remote",
        "url": "https://api.example.com/mcp",
        "auth": {
          "type": "oauth",
          "client_id": "{env:OAUTH_CLIENT_ID}",
          "client_secret": "{env:OAUTH_CLIENT_SECRET}",
          "callback_port": 8080,
          "redirect_uri": "http://localhost:8080/callback"
        }
      }
    }
  }
}

Gotcha: V2 renames OAuth fields to snake case: clientId becomes client_id, clientSecret becomes client_secret, callbackPort becomes callback_port, and redirectUri becomes redirect_uri.

Timeouts

V2 separates timeout purposes:

{
  "mcp": {
    "servers": {
      "slow-server": {
        "type": "local",
        "command": ["node", "server.js"],
        "timeout": {
          "catalog": 30000,
          "execution": 60000
        }
      }
    }
  }
}

V1 to V2 Migration

// V1
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

// V2
{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp"],
        "disabled": false,
        "timeout": {
          "catalog": 30000,
          "execution": 30000
        }
      }
    }
  }
}

Key changes: servers move under mcp.servers, enabled becomes the inverse disabled, and the single timeout splits into catalog and execution.