bug(claude-code): authenticated MCP ignores headersHelper and returns 401

[frf12]

Summary

The Claude Code plugin configures authenticated HTTP MCP transport through headersHelper, but Claude Code does not apply the generated Authorization header to the PowerContext MCP request. The plugin is enabled and the Server is reachable, yet /plugin reports the PowerContext MCP Server as unauthenticated and failed with HTTP 401.

Environment

• PowerContext plugin: 0.1.0 from commit 245601d3f69a6ab3c790eb6318be391bb61f6966
• Claude Code: reproduced on 2.1.89 and the current 2.1.258
• PowerContext Server: authenticated HTTP endpoint on http://127.0.0.1:8000/mcp
• Host: Linux over SSH

Reproduction

1. Run PowerContext Server with enforced access and a configured auth token.

2. Export the matching complete header before starting Claude Code:

   export POWERCONTEXT_CLAUDE_AUTHORIZATION="Bearer $POWERCONTEXT_SERVER_AUTH_TOKEN"
   claude

3. Enable powercontext@powercontext.

4. Open /plugin and inspect the PowerContext MCP Server.

Actual behavior

The plugin is enabled, but its MCP Server reports:

Status: failed
Auth: not authenticated
URL: http://127.0.0.1:8000/mcp
SDK auth failed: HTTP 401

The Server receives no valid credential and returns unauthorized.

Evidence

• The running Claude process contains POWERCONTEXT_CLAUDE_AUTHORIZATION.

• Its value exactly matches Bearer <POWERCONTEXT_SERVER_AUTH_TOKEN> without printing either credential.

• Running the configured headersHelper in that same process environment exits successfully and emits an Authorization string.

• A direct request using that emitted header passes Server authentication (it reaches MCP content negotiation instead of returning 401).

• Replacing headersHelper with Claude Code's documented environment-expanded headers configuration makes claude mcp list report:

  plugin:powercontext:powercontext: http://127.0.0.1:8000/mcp (HTTP) - ✔ Connected
  

Working configuration:

{
  "powercontext": {
    "type": "http",
    "url": "${user_config.server_url}/mcp",
    "headers": {
      "Authorization": "${POWERCONTEXT_CLAUDE_AUTHORIZATION}"
    }
  }
}

Root cause and test gap

The distributed .mcp.json relies on headersHelper. Existing contract and service-chain tests execute the helper independently, but do not verify that a real Claude Code MCP client consumes that field and sends the resulting header. This allows the helper tests to pass while the installed plugin still fails authentication.

The current English and Chinese setup/troubleshooting documentation also states that MCP reads the credential through headersHelper, so it directs users toward a path that does not work in the tested Claude Code releases.

Proposed fix

• Replace headersHelper with an environment-expanded headers.Authorization entry.
• Update the contract test to assert the installed MCP configuration.
• Update English and Chinese Claude Code setup and troubleshooting documentation.
• Preserve the rule that credentials are supplied through process environment and are never committed to the plugin or repository.