[BUG] HTTP MCP server returning RFC 6750 401 without RFC 9728 `resource_metadata=` hint surfaces as 'Failed to connect' instead of triggering OAuth dance

Server-side update: I shipped a corresponding backend fix on our SpeakUp MCP AS that adds the RFC 9728 resource_metadata= parameter to the WWW-Authenticate header on every 401 from /v2/mcp/transport/. Live as of 2026-05-22 06:16Z on api.speak-up.pro.

Updated server response:

$ curl -sS -i -X POST https://api.speak-up.pro/v2/mcp/transport/ \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize", \
         "params":{"protocolVersion":"2024-11-05","capabilities":{}, \
                   "clientInfo":{"name":"t","version":"1"}}}' | grep -iE 'HTTP/|www-authenticate'
HTTP/2 401
www-authenticate: Bearer error="invalid_token", resource_metadata="https://api.speak-up.pro/.well-known/oauth-protected-resource"

So the bug repro is now even cleaner: the server emits the RFC 9728 discovery breadcrumb the client needs, and the linked PRM document at https://api.speak-up.pro/.well-known/oauth-protected-resource is also live (200 OK, full document with authorization_servers, scopes_supported, etc.). With ~/.claude.json speakup-prod set to {"type": "http", "url": "https://api.speak-up.pro/v2/mcp/transport/", "headers": {}}, claude mcp list should now flip from ✗ Failed to connect to ! Needs authentication once the CLI honours either the resource_metadata= hint OR the apex /.well-known/oauth-authorization-server fallback. Today it still shows Failed to connect, confirming the gap is entirely client-side.

Backend PR for reference (squash 4823241c): https://github.com/TheSpeakUp/speak_up_backend/pull/708 — diff is two helpers + two call-site swaps in src/MCP/hosted_runtime.py, plus three test assertions. Trivial change on the server, but the CLI still needs the discovery fallback to unlock the OAuth dance for any backend that ships RFC 6750 + RFC 8414 + RFC 9728.

Second server-side fix shipped: the resource_metadata= hint from PR #708 unlocked discovery, but my own debug log against the freshly deployed AS then surfaced a deeper bug — strict Zod parsing rejecting null on optional fields like service_documentation.

[ERROR] MCP server "speakup-prod" ZodError: [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": [ "service_documentation" ],
    "message": "Invalid input: expected string, received null"
  }
]

Fix shipped via https://github.com/TheSpeakUp/speak_up_backend/pull/710 (squash e5924cc4, deployed 2026-05-22 06:35Z) — response_model_exclude_none=True on all 7 well-known metadata routes. Post-deploy curl -sS https://api.speak-up.pro/.well-known/oauth-authorization-server | jq 'with_entries(select(.value == null))' returns {} (was {"service_documentation": null} before).

Claude Code debug log after both fixes:

2026-05-22T06:36:02.293Z [DEBUG] MCP server "speakup-prod": Skipping connection (cached needs-auth)

= no more ZodError, server is now correctly classified as needs-auth.

Remaining cosmetic gap on the client side: claude mcp list still surfaces ✗ Failed to connect for speakup-prod even though the debug log says cached needs-auth. The real OAuth dance is presumably gated on an actual tool call from a chat session, not the headless probe — so mcp list lies. If the intent is for mcp list to also flip to ! Needs authentication once a server is correctly classified as needing auth (the way other built-in connectors do), that branching is the only thing keeping speakup-prod from looking fully wired in the CLI. The user-facing flow inside a real chat session should now actually trigger the browser dance — I'll confirm that next.

Solution: MCP OAuth 401 Without resource_metadata Hint

Root Cause

Claude Code's MCP HTTP transport requires the RFC 9728 resource_metadata WWW-Authenticate parameter to initiate OAuth, but many servers only send RFC 6750-compliant 401 responses without this hint. The code treats an OPTIONAL parameter as mandatory.

Proposed Fix

1. Fallback Well-Known URI Discovery - When resource_metadata is absent, derive /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server from the server origin.

2. OAuth Flow Initiation - Support Authorization Code (PKCE) and Device Authorization flows with discovered metadata.

3. Manual OAuth Config Override - Allow users to configure OAuth parameters in mcpServers config.

4. Enhanced Error Messages - Actionable guidance when no OAuth metadata can be discovered.

Testing

• Unit: parseBearerChallenge with/without resource_metadata
• Integration: RFC 6750-only server + RFC 9728 server
• Regression: Existing RFC 9728 servers still work

Impact

• Severity: High - custom MCP servers without RFC 9728 hints broken
• Fix Risk: Low - adds fallback path
• Backward Compatible: Yes

Full solution: solutions/claude-code-61376-mcp-oauth-401-resource-metadata-hint-fix.md

Thanks for the report and the server-side debugging notes. This is fixed and will ship in the next release.

A ZodError during OAuth discovery (e.g. service_documentation: null or other optional-field schema mismatches) is now classified as needs-auth rather than failed, so the authentication prompt surfaces correctly instead of the connector silently disappearing.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.