HTTP MCP Server "Failed to connect" Despite Successful Manual Testing

HTTP MCP Server "Failed to connect" Despite Successful Manual Testing

Environment

• Claude Code Version: 2.0.37
• OS: Linux 6.14.0-35-generic
• Node.js Version: (from pnpm environment)
• Installation Method: (appears to be global via npm based on .claude.json)

Issue Description

HTTP MCP server shows "✗ Failed to connect" in claude mcp list despite the server responding correctly to all manual connection tests.

MCP Server Details

• Server Type: HTTP (Streamable HTTP transport per MCP spec 2024-11-05)
• URL: https://issues.tafoyaventures.com/api/mcp
• Authentication: Bearer token in Authorization header
• Implementation: Next.js 14 App Router endpoint

Configuration

{
  "type": "http",
  "url": "https://issues.tafoyaventures.com/api/mcp",
  "headers": {
    "Authorization": "Bearer [REDACTED]"
  }
}

Added via:

claude mcp add --transport http nextbt https://issues.tafoyaventures.com/api/mcp \
  --header "Authorization: Bearer [TOKEN]" --scope user

Steps to Reproduce

1. Configure HTTP MCP server with Bearer token authentication
2. Run claude mcp list
3. Observe "Failed to connect" status

Expected Behavior

MCP server should show "✓ Connected" status when health check succeeds

Actual Behavior

Shows "✗ Failed to connect" despite server responding correctly to all manual tests

Manual Testing Results

Test 1: curl with initialize

curl -X POST https://issues.tafoyaventures.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Mcp-Protocol-Version: 2024-11-05" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}'

Result: ✅ Success

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

Response Headers:

• mcp-protocol-version: 2024-11-05
• mcp-session-id: [UUID]
• content-type: application/json
• Status: 200 OK

Test 2: Node.js HTTPS client

✅ Successful connection and initialize response with proper session ID

Test 3: tools/list endpoint

curl -s -X POST https://issues.tafoyaventures.com/api/mcp \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Mcp-Session-Id: [SESSION]" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Result: ✅ Success - Returns 7 tools with proper JSON-RPC 2.0 format

Server Implementation Details

The server correctly implements:

• ✅ POST /api/mcp for JSON-RPC messages
• ✅ GET /api/mcp for optional SSE streaming
• ✅ Bearer token authentication validation
• ✅ Session management with Mcp-Session-Id header
• ✅ Protocol version negotiation
• ✅ All MCP 2.0 protocol methods (initialize, tools/list, tools/call, resources/list, resources/read, ping)
• ✅ Proper JSON-RPC 2.0 responses with correct status codes
• ✅ HTTPS with valid Let's Encrypt certificate

Comparison with Working Servers

Other MCP servers showing "✓ Connected":

• playwright (stdio) - ✓ Connected
• chrome-devtools (stdio) - ✓ Connected
• sequential-thinking (stdio) - ✓ Connected
• serena (stdio) - ✓ Connected
• magic (stdio) - ✓ Connected
• context7 (stdio) - ✓ Connected
• accessibility-scanner (stdio) - ✓ Connected

Note: All working servers use stdio transport, not HTTP

Hypothesis

Claude Code's HTTP MCP client health check may be:

1. Not sending required headers (Authorization, Mcp-Protocol-Version)
2. Not handling session initialization correctly
3. Using different timeout/connection parameters than manual tests
4. Having issues with HTTPS/TLS verification
5. Not compatible with the Streamable HTTP transport implementation

Additional Context

• Server works perfectly with manual curl/Node.js testing
• Configuration follows official documentation from https://code.claude.com/docs/en/mcp
• No error messages in Claude Code output beyond "Failed to connect"
• No debug logs found in ~/.claude/logs/debug.log

Workaround

None found. The server cannot be used in Claude Code despite being fully functional.

Related Issues

• Similar "Failed to connect" issues reported for Windows: #4793
• Pattern suggests HTTP transport may have broader compatibility issues

Request

Could you provide:

1. Debug logging for HTTP MCP connection attempts
2. Specific requirements for HTTP MCP server health checks
3. Differences between claude mcp list health check vs actual usage
4. Whether HTTP transport is fully supported in Claude Code 2.0.37

Thank you for investigating this issue!