claude-code - 💡(How to fix) Fix [DOCS] Plugin MCP server docs omit optional blank `userConfig` substitution behavior [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

User configuration and ${user_config.KEY} substitution for plugin-provided MCP servers

Current Documentation

The docs currently say:

The userConfig field declares values that Claude Code prompts the user for when the plugin is enabled. Use this instead of requiring users to hand-edit settings.json.

Keys must be valid identifiers. Each value is available for substitution as ${user_config.KEY} in MCP and LSP server configs, hook commands, and (for non-sensitive values only) skill and agent content. Values are also exported to plugin subprocesses as CLAUDE_PLUGIN_OPTION_<KEY> environment variables.

The MCP page also says:

Plugins define MCP servers in .mcp.json at the plugin root or inline in plugin.json

• When a plugin is enabled, its MCP servers start automatically

Neither page explains how optional plugin userConfig fields behave when a user leaves a value blank and that value is referenced from a plugin MCP server config.

What's Wrong or Missing?

Changelog v2.1.119 includes this entry:

Fixed plugin MCP servers failing when ${user_config.*} references an optional field left blank

The current docs explain that ${user_config.KEY} substitution exists, but they do not document the optional/blank-value case for plugin configuration.

That leaves plugin authors without guidance on:

1. whether a plugin userConfig field can be optional,
2. what happens when the user leaves that field blank, and
3. how plugin-provided MCP servers should behave when their config references that blank value.

Because this behavior was important enough to be fixed in v2.1.119, it should be documented as supported behavior rather than discoverable only through a changelog bug-fix note.

Suggested Improvement

Add a short subsection under User configuration in plugins-reference that documents:

• how plugin authors define an optional userConfig field,
• what runtime value/substitution behavior Claude Code uses when that field is left blank,
• that referencing a blank optional value from plugin MCP server config should not cause the server to fail, and
• one example showing a plugin MCP server config that safely references an optional userConfig field.

Also add a brief cross-reference from the plugin MCP section in https://code.claude.com/docs/en/mcp back to the plugins-reference explanation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.119

Exact changelog entry: Fixed plugin MCP servers failing when ${user_config.*} references an optional field left blank