[BUG] Claude Code HTTP MCP Transport - Connection Failure

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Summary
Claude Code v2.1.7 fails to connect to a custom HTTP MCP server despite the server being fully functional and responding correctly to curl requests from the same machine.

Environment
Claude Code version: 2.1.7
Node.js version: v20.20.0
Platform: Linux (Ubuntu, running in Proxmox LXC)
Transport types tested: http, sse

Setup
Custom MCP server running behind Traefik reverse proxy with valid Let's Encrypt TLS certificate. The server implements the MCP JSON-RPC protocol over HTTP.

MCP Configuration
json{
"mcpServers": {
"thebrain": {
"type": "http",
"url": "https://my-mcp-server.example.com/mcp"
}
}
}

Added via: claude mcp add --transport http --scope user thebrain https://my-mcp-server.example.com/mcp

The Problem
claude mcp list consistently reports "Failed to connect" for the HTTP MCP server.
Checking MCP server health...
thebrain: https://my-mcp-server.example.com/mcp (HTTP) - ✗ Failed to connect

Key Observations
"hasAuthProvider":true - This appears even though no authentication was configured. Is there a way to disable this?
"No token data found" - Repeated three times before failure. The server doesn't require authentication.
Inconsistent error - Debug logs show "HTTP 404" error, but NODE_DEBUG=undici shows HTTP 200 being received.
TLS works fine - NODE_DEBUG=tls shows successful handshake:
TLS: client _finishInit handle? true alpn http/1.1 servername my-mcp-server.example.com
TLS: client emit secureConnect. authorized: true

Questions
Is there documentation for the expected HTTP MCP server protocol beyond the basic MCP spec?
How can we configure an HTTP MCP without authentication (disable hasAuthProvider)?
Is there a specific endpoint or response format expected for health checks?
Why does the debug log show HTTP 404 when undici shows HTTP 200?

Attempted Solutions
Tried both http and sse transport types - same failure
Added SSE endpoint support (GET /mcp returns text/event-stream) - still fails
Verified DNS resolution works correctly
Verified TLS certificate is valid
Tested with HTTP/1.1 explicitly - works with curl
Server handles double-slash URLs (//mcp) gracefully

What Should Happen?

Requested Outcome
Documentation or guidance on:
The exact HTTP protocol/endpoints Claude Code's HTTP transport expects
How to configure HTTP MCP servers without OAuth/authentication
Any undocumented requirements for HTTP MCP compatibility

Error Messages/Logs

NODE_DEBUG shows HTTP 200 response
$ NODE_DEBUG=undici claude mcp list 2>&1 | grep -E "(sending|received)"

UNDICI: sending request to POST https://my-mcp-server.example.com//mcp
UNDICI: received response to POST https://my-mcp-server.example.com//mcp - HTTP 200
The server returns HTTP 200, yet Claude Code reports "Failed to connect".
Debug Log Analysis
From ~/.claude/debug/ logs during interactive session startup:
MCP server "thebrain": Initializing HTTP transport to https://my-mcp-server.example.com/mcp
MCP server "thebrain": HTTP transport options: {"url":"...","headers":{"User-Agent":"claude-code/2.1.7"},"hasAuthProvider":true,"timeoutMs":60000}
MCP server "thebrain": HTTP transport created successfully
MCP server "thebrain": Starting connection with timeout of 30000ms
MCP server "thebrain": No token data found
MCP server "thebrain": No token data found
MCP server "thebrain": No token data found
MCP server "thebrain": SSE Connection failed after 50ms: {"error":"Error POSTing to endpoint (HTTP 404): Not found"}

Steps to Reproduce

1. curl from the same machine succeeds

bash$ curl -s -X POST "https://my-mcp-server.example.com/mcp" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"thebrain-mcp","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

1. tools/list worksbash$ curl -s -X POST "https://my-mcp-server.example.com/mcp" \ -H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

{"result":{"tools":[...27 tools returned...]},"jsonrpc":"2.0","id":1}

1. NODE_DEBUG shows HTTP 200 response

$ NODE_DEBUG=undici claude mcp list 2>&1 | grep -E "(sending|received)"

UNDICI: sending request to POST https://my-mcp-server.example.com//mcp
UNDICI: received response to POST https://my-mcp-server.example.com//mcp - HTTP 200
The server returns HTTP 200, yet Claude Code reports "Failed to connect".
Debug Log Analysis
From ~/.claude/debug/ logs during interactive session startup:
MCP server "thebrain": Initializing HTTP transport to https://my-mcp-server.example.com/mcp
MCP server "thebrain": HTTP transport options: {"url":"...","headers":{"User-Agent":"claude-code/2.1.7"},"hasAuthProvider":true,"timeoutMs":60000}
MCP server "thebrain": HTTP transport created successfully
MCP server "thebrain": Starting connection with timeout of 30000ms
MCP server "thebrain": No token data found
MCP server "thebrain": No token data found
MCP server "thebrain": No token data found
MCP server "thebrain": SSE Connection failed after 50ms: {"error":"Error POSTing to endpoint (HTTP 404): Not found"}

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.7

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_