--plugin-dir does not load MCP servers defined in plugin.json

Resolved 💬 1 comment Opened Dec 24, 2025 by hughescr Closed Jan 2, 2026

Description

When using --plugin-dir to load a local plugin, MCP servers defined in the plugin's plugin.json (via the mcpServers field) are not loaded. Only commands, agents, skills, and hooks from the plugin are loaded.

Steps to Reproduce

  1. Create a plugin directory structure:
~/.claude/plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── .mcp.json
  1. Configure plugin.json to reference the MCP server:
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin with MCP server",
  "mcpServers": ".mcp.json"
}
  1. Configure .mcp.json with an MCP server:
{
  "MyServer": {
    "command": "npx",
    "args": ["my-mcp-server"]
  }
}
  1. Launch Claude Code with the plugin:
claude --plugin-dir ~/.claude/plugins/my-plugin
  1. Check available MCP tools - the MCP server tools are not available

Expected Behavior

MCP servers defined in plugin.json via the mcpServers field should be loaded and started when the plugin is loaded via --plugin-dir.

Actual Behavior

  • Plugin components (agents, skills, commands, hooks) are loaded correctly
  • MCP servers defined in the plugin are not loaded
  • MCP server tools are not available in the session

Workaround

Use --mcp-config flag in addition to --plugin-dir:

claude --plugin-dir ~/.claude/plugins/my-plugin --mcp-config ~/.claude/plugins/my-plugin/.mcp.json

Environment

  • Claude Code: latest (via bunx @anthropic-ai/claude-code@latest)
  • OS: macOS
  • Shell: zsh

Additional Context

The plugins documentation indicates that plugins can define MCP servers via plugin.json, but this only works when plugins are formally installed via claude plugin install and enabled. The --plugin-dir flag for session-only plugin loading does not appear to handle the mcpServers field.

This creates an inconsistency where --plugin-dir partially loads plugins - loading some components but not others.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗