fix: detect 401 errors from StreamableHTTP transport for OAuth flow

[olaservo]

Summary

Fix for Streamable HTTP WWW-Authenticate challenge not triggering OAuth flow in version 0.17.5.

When an OAuth-protected MCP server returns a 401 WWW-Authenticate challenge via Streamable HTTP transport, the proxy was returning 500 instead of 401 to the client. This prevented the client-side OAuth discovery and redirect flow from triggering.

Note: Inspector V2 is under development to address architectural and UX improvements. During this time, V1 contributions should focus on bug fixes and MCP spec compliance. See CONTRIBUTING.md for more details.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Refactoring (no functional changes)
• Test updates
• Build/CI improvements

Changes Made

The server-side error handling only checked for SseError instances when detecting 401 responses from MCP servers. However, StreamableHTTPClientTransport throws a different error type (generic Error with "HTTP 401" in the message) when there's no authProvider configured on the server-side transport.

Changes:

1. Imported StreamableHTTPError from the SDK
2. Added is401Error() helper function that detects 401 errors from:
   • SseError with code 401 (existing behavior)
   • StreamableHTTPError with code 401 (new)
   • Generic Error with "HTTP 401" or "(401)" in message (fallback)
3. Updated error handling in /mcp, /stdio, and /sse routes to use the new helper

Related Issues

Fixes #960

Testing

• Tested in UI mode
• Tested in CLI mode
• Tested with STDIO transport
• Tested with SSE transport
• Tested with Streamable HTTP transport
• Added/updated automated tests
• Manual testing performed

Test Results and/or Instructions

How to test this fix:

1. Set up an MCP server with OAuth protection that returns a WWW-Authenticate header on 401
2. Start the Inspector and select "Streamable HTTP" transport
3. Enter the OAuth-protected MCP server URL
4. Click Connect
5. Expected (with fix): OAuth flow is triggered - user is redirected to authorization page
6. Before fix: Shows "Connection Error - Check if your MCP server is running and proxy token is correct"

Note: The server package currently lacks test infrastructure. The is401Error() helper is a simple pure function. Automated tests could be added when server-side test infrastructure is established.

Checklist

• Code follows the style guidelines (ran npm run prettier-fix)
• Self-review completed
• Code is commented where necessary
• Documentation updated (README, comments, etc.)

Breaking Changes

None

Additional Context

Root Cause Analysis:

The SDK's StreamableHTTPClientTransport.send() method handles 401 responses differently depending on whether an authProvider is configured:

• With authProvider: Attempts OAuth flow internally
• Without authProvider: Throws Error('Error POSTing to endpoint (HTTP 401): ...')

The Inspector's proxy server creates transports without an authProvider (the OAuth flow is handled client-side), so it receives the generic Error. The existing error handler only checked for SseError, causing the 401 to be returned as a 500.

🤖 Generated with Claude Code