MCP Servers

Model Context Protocol (MCP) servers extend opencode with external tools for browser automation, documentation lookup, database access, and more.

What is MCP?#

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Created by Anthropic, it provides a standardized way for AI assistants to access capabilities like:

  • Browser automation - Control browsers for testing, screenshots, and web scraping
  • Documentation lookup - Access up-to-date library docs and code examples
  • Database access - Query and modify databases safely
  • File system operations - Read and write files in sandboxed environments
  • API integrations - Connect to third-party services and APIs

Optional Integration#

MCP is Optional

MCP servers are optional enhancements, not requirements. yo, go works without any MCP servers configured. When an MCP tool is unavailable, agents automatically fall back to alternative approaches:

  • •Browser automation: Falls back to Playwright CLI or direct library usage
  • •Documentation lookup: Uses documentation tools if available, otherwise upstream docs
  • •Database access: Uses project-specific database clients directly

Server Types#

opencode supports two types of MCP servers:

Local Servers

Run as a local process on your machine. You provide a command and opencode starts the server automatically. Good for tools that need access to local files or system resources.

Remote Servers

Connect to a hosted MCP server via URL. No local installation needed. The server may require OAuth authentication for secure access.

Configuration#

MCP servers are configured in your ~/.config/opencode/opencode.json file under the mcp key.

Local Server Configuration#

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest",
        "--headless",
        "--caps=vision,pdf,test"
      ],
      "env": {
        "DEBUG": "true"
      },
      "enabled": true,
      "timeout": 10000
    }
  }
}

type: Must be "local" for local servers

command: Array of command and arguments to start the server

env: Optional environment variables to set

enabled: Set to true to auto-start on launch

timeout: Request timeout in milliseconds (default: 5000)

Remote Server Configuration#

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true,
      "oauth": {
        "clientId": "your-client-id",
        "scopes": ["read", "write"]
      }
    }
  }
}

type: Must be "remote" for remote servers

url: The MCP server endpoint URL

oauth: Optional OAuth configuration (set to false to disable auto-detection)

Popular MCP Servers#

Here are some commonly used MCP servers that work well with yo, go:

Playwright

local

Browser automation for testing, screenshots, and web scraping. Supports vision capabilities for analyzing page content.

"playwright": {
  "type": "local",
  "command": [
    "npx",
    "@playwright/mcp@latest",
    "--headless",
    "--caps=vision,pdf,test,tracing",
    "--ignore-https-errors"
  ],
  "enabled": true
}

Context7

remote

Up-to-date documentation lookup for libraries and frameworks. Provides code examples and API references.

"context7": {
  "type": "remote",
  "url": "https://mcp.context7.com/mcp",
  "enabled": true
}

Supabase

local

Database access for Supabase projects. Query tables, manage schemas, and interact with your Postgres database.

"supabase": {
  "type": "local",
  "command": [
    "npx",
    "@supabase/mcp@latest",
    "--project-ref=your-project-ref"
  ],
  "env": {
    "SUPABASE_ACCESS_TOKEN": "your-access-token"
  },
  "enabled": true
}

OAuth Authentication#

Some remote MCP servers require OAuth authentication. opencode handles the OAuth flow automatically when configured.

OAuth Flow

When you first use an OAuth-protected MCP server, opencode will open a browser window for authentication. After authorizing, the credentials are stored securely and reused for future sessions.

To configure OAuth:

  1. Add the oauth configuration to your server entry
  2. Specify the clientId from your OAuth application
  3. List the required scopes for the server
  4. Run opencode - it will prompt for authentication on first use

Using MCP Tools#

Once an MCP server is connected, its tools become available to agents automatically. Agents can discover and use these tools based on their capabilities.

Example: Using Playwright

With Playwright MCP enabled, agents can take screenshots, interact with pages, and run E2E tests:

User: Take a screenshot of https://example.com

Agent: I'll use Playwright to capture that screenshot...

Troubleshooting#

Server not connecting

Check that enabled: true is set and the command/URL is correct. For local servers, ensure the required packages are installed.

Timeout errors

Increase the timeout value in your configuration. Default is 5000ms (5 seconds).

OAuth issues

Clear stored credentials and re-authenticate. Check that your OAuth application has the correct redirect URLs configured.

ScaffoldsAutomations