[FEATURE] Support user-configurable environment variables in plugin/marketplace MCP servers

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Plugins that include MCP servers often need user-specific configuration (e.g., working directories, API endpoints, credentials). Currently, there is no supported mechanism for users to set or override environment variables for MCP servers installed via plugins.

The env block in a plugin's .mcp.json is static and baked into the plugin source. Users cannot customize these values without:

1. Manually editing cached plugin files (fragile, overwritten on update)
2. Setting global shell environment variables (leaks across contexts, not discoverable)
3. Hardcoding values into the plugin that only work for one user/environment

This is a significant gap for organizations distributing shared plugins via private marketplaces, where the plugin author cannot know each user's local paths, credentials, or preferences at authoring time.

Proposed Solution

Support a userEnv (or similar) field in plugin MCP server configuration that declares environment variables the user must or may provide, with optional defaults and descriptions.

Example plugin .mcp.json

{
  "mcpServers": {
    "orchestrate": {
      "command": "/path/to/server.py",
      "env": {
        "ORCHESTRATE_EXECUTION_MODE": "slurm"
      },
      "userEnv": {
        "ORCHESTRATE_WORK_DIR": {
          "description": "Working directory for job outputs",
          "required": false,
          "default": "~/orchestrate"
        },
        "ORCHESTRATE_CONTAINER_DIR": {
          "description": "Path to Apptainer/Singularity container images",
          "required": true
        }
      }
    }
  }
}

User configuration

Users would set their values in a supported location (e.g., user-scoped settings, .claude/settings.json, or via claude mcp configure):

{
  "pluginEnv": {
    "orchestrate-mcp@MyOrg": {
      "ORCHESTRATE_WORK_DIR": "/large_storage/username/orchestrate",
      "ORCHESTRATE_CONTAINER_DIR": "/large_storage/public/apptainer"
    }
  }
}

Behavior

• env values are set by the plugin author and not user-editable (static config)
• userEnv values are provided by the user and merged at MCP server launch time
• If required: true and no value is provided, Claude Code warns the user on plugin enable or session start
• User values take precedence over default values
• User values should NOT take precedence over env values (plugin author retains control of static config)

Use Case

We maintain a private marketplace with multiple plugins that launch MCP servers on a shared HPC cluster (SLURM). Each user has a different home directory, scratch space, and working directory. The plugin author cannot hardcode these paths. Today there is no clean way for users to provide their own values.

Related Issues

• #9427 — ${VAR} expansion not working in plugin .mcp.json (bug in variable expansion)
• #11927 — env vars from .claude/settings.json not passed to plugins/MCPs (bug in env propagation)
• #17117 — Support defaultEnabled flag for plugins in marketplace.json (related marketplace DX)
• #28310 — Support default/required plugins that auto-install on marketplace add (related marketplace DX)

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

_No response_

Additional Context

_No response_