Plugins & MCP

Plugin management

Claude Code keeps plugins in ~/.claude/plugins/. Each claude-multi instance can have its own set of plugins, either symlinked from ~/.claude (auto-sync) or independently installed.

How plugins are stored

Each instance has a plugins/ directory in its config dir:

~/.claude-deepseek/plugins/
├── some-plugin/              # actual plugin files
│   ├── plugin.json
│   └── ...
└── external_plugins/         # external plugins live here
    └── another-plugin/
        ├── plugin.json
        └── ...

claude-multi records plugin state in installed_plugins.json (v2 format) with scope, install path, version, and timestamps.

Listing plugins

TUI: Select Manage plugins, pick an instance, and see all installed plugins with their status.

CLI:

# List all available default plugins
claude-multi plugins list-defaults

# List installed plugins for a specific instance
claude-multi plugins list-installed deepseek

Default plugins show a category badge ([internal] or [ext]) and an MCP indicator when the plugin provides MCP servers.

Installing plugins

TUI: Select Manage plugins → pick an instance → Install → multi-select from the list. space toggles, enter confirms.

CLI:

claude-multi plugins install deepseek <plugin-id> [<plugin-id>...]

Before installing, claude-multi checks for collisions. If a new plugin would conflict with an existing one (same MCP server name, different content), it warns you before writing anything.

Enabling and disabling

Toggle a plugin without uninstalling it:

claude-multi plugins enable deepseek <plugin-id>
claude-multi plugins disable deepseek <plugin-id>

Copying between instances

Copy one or more plugins from one instance to another:

claude-multi plugins copy <source-instance> <dest-instance> <plugin-id> [<plugin-id>...]

Removing plugins

claude-multi plugins remove deepseek <plugin-id> [<plugin-id>...]

Removal renames the plugin directory to a backup rather than deleting it outright.

Collision detection

If you have installed the same plugin in two places, one symlinked and one copied, their MCP server names can conflict:

claude-multi plugins check-collisions deepseek <plugin-id> [<plugin-id>...]

This scans for plugins that share an MCP server name but have different content.

Auto-sync and symlinks

Sync has three modes, which control how an instance’s plugins/ and skills/ relate to ~/.claude/:

• auto: plugins/ and skills/ are symlinked whole to ~/.claude/. Install or update a plugin once and every synced instance sees it immediately. Per-plugin operations (install/remove/enable/disable) aren’t available, since changes happen at the source.
• half-manual: real directories, but each plugin and skill inside is individually symlinked back to ~/.claude/. You keep the existing set, but new installs in ~/.claude don’t appear until you re-sync. Per-plugin management is blocked here too.
• full-manual: independent copies with no symlinks. The instance can drift freely from ~/.claude/, and all per-plugin operations work.

# Set or change the mode
claude-multi auto-sync deepseek auto
claude-multi auto-sync deepseek half-manual
claude-multi auto-sync deepseek full-manual

# Legacy on/off still works (on → auto, off → full-manual)
claude-multi auto-sync deepseek on
claude-multi auto-sync deepseek off

Conversions are one-way: auto → half-manual → full-manual. You can’t step back up, because reconciling directories that have diverged is a data-loss problem.

Repairing broken symlinks

If you move or delete ~/.claude, symlinks across every synced instance break. Rebuild them with:

claude-multi fix-symlinks [names...]

Run it for specific instances, or with -a/--all across all of them. From the TUI, Re-sync symlinks does the same thing.

---

MCP server management

MCP (Model Context Protocol) servers let Claude Code talk to outside systems: databases, APIs, file systems, and whatever else you wire up. Each instance can have its own MCP server configuration.

Listing MCP servers

TUI: Select MCP servers from the main menu.

CLI:

claude-multi mcp list

This prints the MCP server configs from every instance, so you can see what is connected where.

Copying between instances

Set up an MCP server in one instance and want it in another:

claude-multi mcp copy

From the TUI, select MCP servers → Copy. Pick source and destination instances.

Verifying configs

MCP server configs can go stale if a server binary gets moved or removed:

claude-multi mcp verify

This checks that the referenced executables and paths still exist.

Adding MCP servers

TUI: Select MCP servers → pick an instance → Add custom server. Enter the server name and JSON config.

MCP configs use the same format as Claude Code’s native MCP config, with no extra layer on top.

Where configs live

Each instance stores MCP server configuration in its own settings.json:

~/.claude-deepseek/settings.json → mcpServers field

Setting up MCP during instance creation

When creating a new instance through the TUI, the Copy Options step lets you bring over MCP server configs from your default ~/.claude install. Use --copy-mcp on the CLI:

claude-multi add new-instance --provider deepseek --api-key sk-... --copy-mcp

Example: filesystem and database servers

Edit an instance’s settings.json directly to add a server manually:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects/my-app"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

Restart the instance and the servers load automatically. Inside a session, /mcp lists every connected server and its available tools.

Isolating servers per instance

Some servers should reach only specific instances. A production database server has no business being reachable from a sandbox instance. Keep auto-sync off for that instance and configure its MCP servers in its own settings.json:

~/.claude-glm/settings.json          # includes the postgres MCP server
~/.claude-sandbox/settings.json      # no postgres MCP server

Troubleshooting

Problem	Fix
Server not loading	Check the command path in settings.json
Permission denied	Make sure the MCP binary is executable (chmod +x)
Connection refused	Verify the server is running and the port is correct
Server loads but no tools	Check the server’s own logs for startup errors