opencode-plugin/docs/MCP.md at main · gzb1128/opencode-plugin · GitHub
Skip to content

MCP.md

Latest commit

 

History

History
360 lines (278 loc) · 7.13 KB

MCP.md

File metadata and controls

360 lines (278 loc) · 7.13 KB
Raw

MCP (Model Context Protocol) Support

OpenCode Plugin CLI can install MCP server configuration from plugins, allowing plugins to register external tool servers with OpenCode.

What is MCP?

MCP (Model Context Protocol) is a protocol that enables Claude Code plugins to:

  • Connect to external services (databases, APIs, file systems)
  • Provide structured tool access within Claude Code
  • Bundle MCP server configuration with plugins

MCP Server Types

1. stdio (Local Process)

Execute local MCP servers as child processes.

Configuration (.mcp.json):

{
  "my-server": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

Use cases:

  • File system access
  • Local database connections
  • Custom MCP servers
  • NPM-packaged MCP servers

2. HTTP/HTTPS

Connect to hosted MCP servers via HTTP.

Configuration:

{
  "my-api": {
    "type": "http",
    "url": "https://api.example.com/mcp"
  }
}

Use cases:

  • Cloud services
  • REST APIs
  • Remote databases

3. SSE (Server-Sent Events)

Connect to MCP servers using Server-Sent Events.

Configuration:

{
  "my-sse-server": {
    "type": "sse",
    "url": "https://sse.example.com/events"
  }
}

4. WebSocket

Connect to MCP servers via WebSocket.

Configuration:

{
  "my-ws-server": {
    "type": "websocket",
    "url": "wss://ws.example.com/mcp"
  }
}

Configuration Methods

Method 1: Dedicated .mcp.json (Recommended)

Create .mcp.json at plugin root. Two formats are supported:

Claude Code Standard Format (Direct)

{
  "my-database": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
  },
  "my-api": {
    "type": "http",
    "url": "https://api.example.com/mcp"
  }
}

Wrapped Format (Legacy)

{
  "mcpServers": {
    "my-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Both formats work identically. The direct format is the Claude Code standard.

Method 2: Inline in plugin.json

Add mcpServers field to plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Note: Both .mcp.json and inline mcpServers are merged when installing a plugin.

Variable Substitution

OpenCode Plugin CLI automatically substitutes variables in MCP configurations:

  • ${CLAUDE_PLUGIN_ROOT} - Path to the plugin directory
  • ${PLUGIN_NAME} - Name of the plugin
  • ${PLUGIN_VERSION} - Version of the plugin

Example:

{
  "my-server": {
    "command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
    "args": ["--port", "8080"],
    "env": {
      "PLUGIN_ROOT": "${CLAUDE_PLUGIN_ROOT}",
      "PLUGIN_NAME": "${PLUGIN_NAME}",
      "PLUGIN_VERSION": "${PLUGIN_VERSION}"
    }
  }
}

Variables are substituted in:

  • command field
  • args array
  • url field
  • env values

Managing MCP Servers

List Installed MCP Servers

opencode-plugin mcp list

Output:

Installed MCP Servers:

NAME                        TYPE     COMMAND/URL
github.github               http     https://api.githubcopilot.com/mcp/
plugin-a.database           stdio    /path/to/plugin/servers/db-server

Total: 2 MCP server(s)

Show MCP Server Details

opencode-plugin mcp show github.github

Output:

MCP Server: github.github

Type: http
URL: https://api.githubcopilot.com/mcp/

Installation

MCP server configuration is registered when you install a plugin that defines MCP servers:

# Install plugin with MCP servers
opencode-plugin plugin install github

# Output:
✓ Successfully installed plugin: github@latest
  From marketplace: claude-plugins-official
  Cache: ~/.opencode-plugin-cli/cache/claude-plugins-official/github/latest
  Skills: 0
  MCP Servers: 1

The MCP configuration is merged into the mcp section of ~/.config/opencode/opencode.json.

Uninstallation

When you remove a plugin, its MCP config entries are also removed:

opencode-plugin plugin remove github

# Output:
✓ Removed cache: ~/.opencode-plugin-cli/cache/claude-plugins-official/github/latest
✓ Successfully removed plugin: github (0 symlinks removed)

MCP Server Conflicts

OpenCode Plugin CLI prefixes installed MCP server names with the plugin name:

plugin-a.database
plugin-b.database

This avoids collisions between different plugin prefixes. Plugins with the same plugin name still share the same MCP prefix.

Real-World Examples

GitHub Plugin

.mcp.json:

{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "headers": {
      "Authorization": "Bearer <github-token>"
    }
  }
}

Header values are copied as written. The CLI does not substitute variables in headers.

Playwright Plugin

.mcp.json:

{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest"]
  }
}

Custom Server Plugin

.mcp.json:

{
  "custom-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
    "args": ["--verbose"],
    "env": {
      "LOG_LEVEL": "info"
    }
  }
}

OAuth and Authentication

For MCP servers that require OAuth or complex authentication:

  1. Environment variables: Provide explicit env values for local servers.
  2. Configuration files: Bundle config files in the plugin.
  3. Interactive setup: Let the server prompt for credentials on first use.

The CLI only substitutes ${CLAUDE_PLUGIN_ROOT}, ${PLUGIN_NAME}, and ${PLUGIN_VERSION}. It does not expand arbitrary shell variables such as ${GITHUB_TOKEN}.

Example:

{
  "github": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/github-mcp",
    "env": {
      "GITHUB_TOKEN": "<token>",
      "GITHUB_ORG": "myorg"
    }
  }
}

Best Practices

1. Use Dedicated .mcp.json

Prefer separate .mcp.json for clarity and maintainability.

2. Prefix Server Names

Use descriptive names that include the service:

{
  "postgres-main": {...},
  "github-api": {...}
}

3. Document Required Variables

Document required environment variables in plugin README.

4. Test Locally

Test MCP servers locally before packaging with plugin.

5. Version MCP Servers

If MCP servers have versions, track them in plugin.json.

Troubleshooting

MCP servers not showing up

  1. Check .mcp.json or plugin.json syntax
  2. Verify ${CLAUDE_PLUGIN_ROOT} paths are correct
  3. Run opencode-plugin mcp list to see installed servers

MCP server not working

  1. Check command path exists
  2. Verify environment variables are set
  3. Check MCP server logs

Conflicts between plugins

MCP servers are prefixed as pluginName.serverName. Plugins with the same plugin name still share a prefix.

See Also