claude-code - 💡(How to fix) Fix Built-in "claude.ai Figma" connector shows "Failed to connect" instead of "Needs authentication"

Summary

The built-in Figma connector (https://mcp.figma.com/mcp) is the only one of the 10 bundled claude.ai * connectors that surfaces as ✗ Failed to connect in claude mcp list. The other 9 (Notion, monday.com, Linear, Intercom, HubSpot, Canva, Box, Atlassian, Asana) all correctly show ! Needs authentication for a not-yet-authorized account.

Reproduction is just running claude mcp list on an account that has not authenticated any of the bundled connectors:

claude.ai Figma:     https://mcp.figma.com/mcp     - ✗ Failed to connect
claude.ai Linear:    https://mcp.linear.app/mcp    - ! Needs authentication
claude.ai Notion:    https://mcp.notion.com/mcp    - ! Needs authentication
... (other 7 also "Needs authentication")

Environment

• Claude Code CLI (Opus 4.7, 1M context)
• macOS 15 (Darwin 25.4.0)
• Claude Desktop "커넥터 > 연결되지 않음" lists Figma (and all other 9) as built-in connector catalog entries — the user has not opted into any of them.

Root cause (likely)

The Figma MCP endpoint is alive and OAuth discovery is well-formed, but the WWW-Authenticate header on the 401 response is non-standard compared to the other 9 connectors.

Figma (failing) — Content-Type: text/plain, body: Unauthorized:

WWW-Authenticate: Bearer resource_metadata="https://mcp.figma.com/.well-known/oauth-protected-resource",scope="mcp:connect",authorization_uri="https://api.figma.com/.well-known/oauth-authorization-server"

Linear (working) — Content-Type: application/json:

WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.linear.app/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing or invalid access token"

Differences that may trip the OAuth client:

1. Figma's response omits error="invalid_token", which RFC 6750 §3 / RFC 9728 expect for missing-token cases.
2. Figma uses a non-standard authorization_uri parameter in WWW-Authenticate instead of relying on resource_metadata alone.
3. Figma's OAuth metadata at /.well-known/oauth-authorization-server includes a non-standard "require_state_parameter": true field.
4. authorization_endpoint (https://www.figma.com/oauth/mcp) is hosted on a different origin than issuer (https://api.figma.com), which may fail strict issuer-origin checks.

Hypothesis: the CLI's MCP OAuth client cannot classify Figma's 401 as "needs reauth" because error="invalid_token" is absent, so it falls through to the generic "connection failed" branch.

Impact

• Cosmetic in the common case (status line shows 1 failed), but it implies the catalog entry is broken when in fact the user simply hasn't authenticated.
• No user-facing remediation:
  • This is a catalog entry pushed via the tengu_claudeai_mcp_connectors feature flag, not a user-added MCP. claude mcp remove cannot target it ("No MCP servers are configured").
  • Claude Desktop's Customize → 데스크톱 ⚙ → 확장 프로그램 → 고급 설정 screen has no toggle to hide built-in catalog entries or disable health-check probes.

Suggested fix

Either (a) be more lenient in the OAuth WWW-Authenticate parser so a Bearer …resource_metadata=… reply without error= is still treated as "needs authentication", or (b) suppress catalog entries from the health-check probe until the user opts in to that connector.