Self-hosted MCP: SDK OAuth handshake fails with HTTP 405 before Bearer token is used

[Mason0920]

Summary

Following the MCP.md setup guide on a self-hosted HyperDX instance, the MCP connection fails with HTTP 405 Method Not Allowed during the SDK's OAuth handshake phase.

Environment

• HyperDX Version: 2.24.1 (self-hosted, Docker)
• Instance URL: https://<domain>:3000 (Next.js frontend with /api/* proxy to API server)
• Client: Claude Code (claude mcp add --transport http)

Steps to Reproduce

1. Generate a Personal API Access Key from Team Settings > API Keys
2. Register MCP server per MCP.md:

   claude mcp add --transport http hyperdx https://<hyperdx-url>/api/mcp \
     --header "Authorization: Bearer <api-key>"

3. Claude Code reports: Failed to connect

Error

Error: SDK auth failed: HTTP 405: Invalid OAuth error response: SyntaxError: JSON Parse error: Unexpected identifier "Method". Raw body: Method Not Allowed

The MCP SDK appears to initiate an OAuth discovery/handshake before using the Bearer token. The self-hosted HyperDX server responds with HTTP 405 "Method Not Allowed" (plain text), which the SDK then fails to parse as a JSON OAuth error response.

The MCP.md documentation instructs using a Bearer token via --header "Authorization: Bearer <key>", but the SDK's HTTP transport seems to attempt OAuth flow first, hitting an endpoint or HTTP method that the self-hosted server does not support.

Expected Behavior

The Bearer token passed via --header should be sufficient for authentication. The SDK should either:

1. Skip OAuth discovery when a Bearer token is already provided, or
2. The self-hosted server should handle the OAuth discovery request gracefully

Questions

1. Is the MCP feature available for self-hosted deployments on v2.24.1? (The route exists on main branch at packages/api/src/api-app.ts:96)
2. Does the self-hosted server need additional configuration to support MCP OAuth flow?
3. Should MCP.md document any version requirement or self-hosted-specific setup steps?

[brandon-pereira]

@Mason0920 hey there,

The MCP server was added in 2.24.0, and I confirmed this morning that the 2.24.1 version does contain the MCP server (I was able to successfully authenticate to it).

Could you please double check that you are using your "Personal API Access Key" from Team Settings in the following format: --header "Authorization: Bearer <personal-api-key>". It could be the incorrect key or you are using your ingestion key instead. If my api key is incorrect I see the below error:

Error: SDK auth failed: HTTP 405: Invalid OAuth error response: SyntaxError: JSON Parse error: Unexpected identifier "Method". Raw body: Method Not Allowed

The MCP uses the same authentication method as the OpenAPI, so running the below command should also work with the same header:

curl https://<hyperdx-url>/api/api/v2 --header "Authorization: Bearer <personal-api-key>"

Should return:

{"version":"v2","user": ..userDetails.. }