[Add Features] MCP Server Management Commands

[dhruvkej9]

MCP Server Management Commands

This PR adds 6 new CLI commands to manage MCP (Model Context Protocol) servers without manually editing configuration files.

Overview

Users can now enable, disable, inspect, and remove MCP servers directly from the command line. All commands follow OpenCode's config hierarchy pattern, where modifications create local overrides in the current directory's opencode.json.

New Commands Added

opencode mcp enable <name>

Enable a disabled MCP server.

• Creates a local override in ./opencode.json if server exists in parent/global config
• Sets enabled: true for the specified server
• Shows config location where change was written

Use case: Quickly enable a globally-configured MCP for a specific project

$ opencode mcp enable playwright
✓ Enabled MCP: playwright [local]

opencode mcp disable <name>

Disable an MCP server.

• Creates a local override in ./opencode.json if server exists in parent/global config
• Sets enabled: false for the specified server
• Useful for temporarily disabling servers per-project

Use case: Disable a global MCP that conflicts with project-specific tooling

$ opencode mcp disable playwright
✓ Disabled MCP: playwright [local]

opencode mcp toggle <name>

Toggle between enabled/disabled states.

• Flips current state: enabled: true ↔ enabled: false
• Creates local override if needed
• Convenient for quick enable/disable without remembering current state

Use case: Quickly switch MCP on/off during debugging

$ opencode mcp toggle playwright
✓ Disabled MCP: playwright [local]

$ opencode mcp toggle playwright
✓ Enabled MCP: playwright [local]

opencode mcp info <name>

Display detailed information about an MCP server:

• Enabled status (✓/✗)
• Server type (local/remote)
• Config location (global/local/relative path)
• Command or URL
• Environment variables (for local servers)
• OAuth status and authentication state (for remote servers)
• Current connection status

Use case: Troubleshoot MCP configuration issues

$ opencode mcp info playwright

┌  MCP Server: playwright
│
●  Enabled:  ✓ Yes
●  Type:     local
●  Config:   global
●  Command:  npx @playwright/mcp@latest
●  Status:   connected
│
└  Done

opencode mcp remove <name>

Remove an MCP server from configuration.

• Finds which config file contains the server
• Shows confirmation prompt with location
• Deletes server entry from the config file
• Prevents accidental deletion with initialValue: false

Use case: Clean up unused MCP servers

$ opencode mcp remove old-server
? Remove 'old-server' from local config? No / Yes
✓ Removed MCP: old-server [local]

opencode mcp completion [shell]

Generate shell completion scripts for tab-completion support.

Supported shells:

• bash - Bash completion script
• zsh - Zsh completion script
• fish - Fish completion script

Features:

• Autocompletes subcommands: add, list, enable, disable, toggle, info, remove, auth, logout, completion
• Autocompletes server names from config (requires jq)
• Auto-detects current shell if not specified
• Provides installation instructions

Use case: Enable tab-completion for faster command entry

Installation:

# Bash - Add to ~/.bashrc
eval "$(opencode mcp completion bash)"

# Zsh - Add to ~/.zshrc
eval "$(opencode mcp completion zsh)"

# Fish
opencode mcp completion fish > ~/.config/fish/completions/opencode-mcp.fish

Example usage:

$ opencode mcp <Tab>
add  list  enable  disable  toggle  info  remove  auth  logout  completion

$ opencode mcp enable <Tab>
playwright  context7  filesystem  puppeteer

Enhanced Existing Commands

opencode mcp list (aliases: ls)

Added: Config location display

Now shows where each MCP server is configured:

• [global] - Defined in ~/.config/opencode/opencode.json
• [local] - Defined in current directory's opencode.json
• [relative/path] - Defined in parent directory or .opencode/ folder

Before:

┌  MCP Servers
│
●  ✓ playwright connected
│      npx @playwright/mcp@latest
│
└  1 server(s)

After:

┌  MCP Servers
│
●  ✓ playwright connected [global]
│      npx @playwright/mcp@latest
│
●  ○ filesystem disabled [local]
│      npx @modelcontextprotocol/server-filesystem
│
└  2 server(s)

Configuration Behavior

All write operations follow OpenCode's standard config hierarchy:

Read (merged from hierarchy)

1. Current directory ./opencode.json
2. Parent directories up to worktree root
3. .opencode/opencode.json directories
4. Global ~/.config/opencode/opencode.json

Write (always nearest)

• All modifications write to ./opencode.json in current directory
• Creates file if it doesn't exist
• Local configs override parent/global configs
• Never modifies global config unless running from ~/.config/opencode/

Example Scenario: Local Override

# Global config has playwright enabled
~/.config/opencode/opencode.json:
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": true
    }
  }
}

# Disable it for a specific project
$ cd ~/my-project
$ opencode mcp disable playwright

# Creates local override
~/my-project/opencode.json:
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": false
    }
  }
}

# Result:
# - playwright is disabled in ~/my-project only
# - playwright remains enabled globally
# - other projects still use global config

Example Scenario: Project-Specific MCP

# Add MCP only for current project
$ cd ~/my-app
$ opencode mcp add
# ... interactive prompts ...

# Saved to ./opencode.json
# Not visible in other projects

Platform Compatibility

✅ All commands work on:

• Linux (Ubuntu, Debian, Arch, etc.)
• macOS
• Windows (WSL, PowerShell, CMD)

All code is written in TypeScript/Bun which is cross-platform.

✅ Shell completions support:

• bash (Linux, macOS, WSL)
• zsh (Linux, macOS, WSL)
• fish (Linux, macOS, Windows, WSL)

Shell completions are optional quality-of-life features and don't affect core functionality.

Complete Command Reference

opencode mcp

Commands:
  opencode mcp add                 add an MCP server
  opencode mcp list                list MCP servers and their status                   [aliases: ls]
  opencode mcp enable <name>       enable an MCP server                                      [NEW]
  opencode mcp disable <name>      disable an MCP server                                     [NEW]
  opencode mcp toggle <name>       toggle MCP server enabled/disabled state                  [NEW]
  opencode mcp info <name>         show details about an MCP server                          [NEW]
  opencode mcp remove <name>       remove an MCP server                                      [NEW]
  opencode mcp auth [name]         authenticate with an OAuth-enabled MCP server
  opencode mcp logout [name]       remove OAuth credentials for an MCP server
  opencode mcp completion [shell]  generate shell completion script                          [NEW]

Options:
  -h, --help        show help                                                              [boolean]
  -v, --version     show version number                                                    [boolean]
      --print-logs  print logs to stderr                                                   [boolean]
      --log-level   log level                   [string] [choices: "DEBUG", "INFO", "WARN", "ERROR"]

Previously existing: add, list, auth, logout New in this PR: enable, disable, toggle, info, remove, completion

Implementation Details

Files Changed

• packages/opencode/src/cli/cmd/mcp.ts - Added 6 new commands and enhanced list command

Helper Functions Added

• findMcpConfigFile(serverName) - Searches config hierarchy to locate which file defines an MCP
• getTargetConfigFile() - Returns local config path for write operations, creates if missing

Code Style

• Follows OpenCode style guide (no unnecessary comments, minimal try/catch, no defensive checks)
• Uses existing patterns from mcp add and mcp auth commands
• Consistent error handling with prompts.log.error() and early returns
• No any casts (except one pre-existing in mcp add for OAuth config)
• Proper TypeScript types throughout

Testing

Tested scenarios:

• ✅ Enable/disable/toggle servers from global config (creates local override)
• ✅ Enable/disable/toggle servers already in local config (modifies in place)
• ✅ Info command shows correct config location for global/local/parent configs
• ✅ Remove command finds and deletes from correct config file
• ✅ Remove command requires confirmation
• ✅ List command shows config locations accurately ([global], [local], relative paths)
• ✅ Completion scripts generate valid bash/zsh/fish syntax
• ✅ All commands respect config hierarchy (read merged, write local)
• ✅ Commands work on Linux/macOS/Windows
• ✅ Shell completions work on bash/zsh/fish

User Impact

Before this PR:

• Users had to manually edit opencode.json files
• Risk of syntax errors in manual JSON editing
• No way to see where MCPs are configured
• No shell tab-completion

After this PR:

• One-command enable/disable/toggle operations
• Safe removal with confirmation prompts
• Clear visibility of config locations with info and list
• Tab-completion for faster command entry
• Project-specific MCP overrides without touching global config

Breaking Changes

None. All new commands, existing commands (add, list, auth, logout) unchanged except for enhancement to list output showing config location.