MCP servers

OpenCode can connect to Model Context Protocol servers and make their tools, prompts, and instructions available to agents. MCP tools consume model context, so enable only the servers you need.

Configure servers

Define each server by a unique name under mcp.servers in your OpenCode configuration. V2 does not place server names directly under mcp.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"]
      }
    }
  }
}

Servers connect automatically unless disabled is true. There is no V2 enabled field.

{
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"],
        "disabled": true
      }
    }
  }
}

As with other configuration, a server in a higher-precedence project config replaces a server with the same name from a lower-precedence config. Use different names when you need separate connections or accounts.

Local servers

A local server is a command that OpenCode starts using the MCP stdio transport.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "everything": {
        "type": "local",
        "command": [
          "npx",
          "-y",
          "@modelcontextprotocol/server-everything"
        ],
        "cwd": ".",
        "environment": {
          "LOG_LEVEL": "info",
          "MCP_API_KEY": "{env:MCP_API_KEY}"
        }
      }
    }
  }
}

Use {env:NAME} to substitute an environment variable while loading config. Shell expressions such as $NAME are not expanded in JSON strings.

Remote servers

A remote server uses the MCP Streamable HTTP transport. Its url must be a valid absolute URL.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false,
        "headers": {
          "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
        }
      }
    }
  }
}

Use oauth: false for a server that exclusively uses an API key or another header-based credential.

OAuth

OAuth support is enabled for remote servers unless oauth is false. OpenCode discovers the authorization server, uses PKCE, refreshes tokens, and attempts dynamic client registration when the server supports it. OAuth credentials are stored outside project configuration.

For a server that supports dynamic client registration, only the remote server is required:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "sentry": {
        "type": "remote",
        "url": "https://mcp.sentry.dev/mcp"
      }
    }
  }
}

When the server reports that it needs authentication, run /connect in the TUI:

/connect

Select the MCP server under Services, then complete the browser authorization flow.

You can also authenticate from the command line:

opencode2 mcp auth sentry

The CLI command prints the authorization URL and waits for the redirect to OpenCode’s loopback callback server.

If the provider issued client credentials, configure them using V2’s snake_case field names:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "company-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp",
        "oauth": {
          "client_id": "{env:MCP_CLIENT_ID}",
          "client_secret": "{env:MCP_CLIENT_SECRET}",
          "scope": "tools:read tools:execute",
          "callback_port": 19876,
          "redirect_uri": "http://127.0.0.1:19876/callback"
        }
      }
    }
  }
}

Remove stored credentials with:

opencode2 mcp logout sentry

Timeouts

Timeouts are positive integer milliseconds. Configure defaults under mcp.timeout; a server’s timeout fields override matching defaults.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timeout": {
      "startup": 45000,
      "catalog": 30000,
      "execution": 600000
    },
    "servers": {
      "slow-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp",
        "timeout": {
          "catalog": 60000
        }
      }
    }
  }
}

Names and permissions

OpenCode combines the server name and MCP tool name as <server>_<tool>. Characters other than letters, numbers, _, and - are replaced with _; for example, server context 7 and tool resolve.library/id become context_7_resolve_library_id. MCP prompts appear as slash commands named <server>:<prompt> using the same normalization.

Choose short server names that remain unique after normalization. Under the default Code Mode, MCP tools are grouped by the normalized server name.

Set codemode to false on a server when its tools should remain on the provider’s native tool list:

{
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "codemode": false
      }
    }
  }
}

Use permission actions to hide or deny a server’s tools without stopping its connection:

{
  "permissions": [
    {
      "action": "context7_*",
      "resource": "*",
      "effect": "deny"
    }
  ]
}

CLI commands

V2 provides these MCP management commands:

# Add a local server to the project config
opencode2 mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything

# Add a remote server to the project config
opencode2 mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'

# Add to the global config instead
opencode2 mcp add context7 --global --url https://mcp.context7.com/mcp

# List configured servers and connection status
opencode2 mcp list

# Authenticate or remove OAuth credentials
opencode2 mcp auth context7
opencode2 mcp logout context7

mcp add accepts either --url for a remote server or a command after -- for a local server, not both. Use --header NAME=VALUE only with remote servers and --env NAME=VALUE only with local servers. Edit the config directly for OAuth, timeout, working-directory, or enablement settings.