claude-code - 💡(How to fix) Fix [DOCS] Plugin .mcp.json example incorrectly uses mcpServers wrapper

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp#plugin-provided-mcp-servers

Section/Topic

Plugin-provided MCP servers — .mcp.json format example

Current Documentation

The docs show this as the correct format for a plugin's .mcp.json:

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

What's Wrong or Missing?

The mcpServers wrapper shown in the .mcp.json example is incorrect. All official plugins in anthropics/claude-plugins-official use the flat format — e.g. context7:

{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"]
  }
}

The mcpServers key is a plugin.json concept — it can reference an external file ("mcpServers": "./my-extra-mcp-config.json") or define servers inline. The .mcp.json file it points to uses the flat format. The docs conflate the two by showing the plugin.json envelope inside the .mcp.json example.

Suggested Improvement

Update the .mcp.json example to use the flat format, consistent with all official plugin examples:

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

Impact

Medium - Makes feature difficult to understand