[BUG] MCP HTTP client fails to connect to Paper MCP server, falls back to auth prompt

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?

Environment

• Claude Code version: 2.1.90
• OS: macOS (Darwin 25.4.0)
• Paper Desktop MCP server: v0.1.10

Summary

Claude Code's MCP Streamable HTTP client does not include the Accept: application/json, text/event-stream header when connecting to MCP servers. This header is required by the MCP Streamable HTTP transport spec. Servers that enforce this requirement (like Paper) return 406 Not Acceptable, which Claude Code misinterprets as an authentication failure.

Two bugs in one

1. Missing Accept header: The Streamable HTTP client doesn't send Accept: application/json, text/event-stream on requests to the MCP endpoint. This violates the transport spec.
2. Incorrect error handling: When the connection fails (406), Claude Code falls back to showing an mcp__paper__authenticate tool instead of surfacing the actual error. This makes debugging very difficult — there's no indication that the server rejected the request due to a missing header.

Failure sequence (observed)

1. Claude Code POSTs to http://127.0.0.1:29979/mcp (initialize)
   → Missing Accept header
   → Server returns 406: "Client must accept both application/json and text/event-stream"

2. Claude Code interprets 406 as "needs authentication"
   → Surfaces mcp__paper__authenticate tool to the user

3. User calls mcp__paper__authenticate
   → Claude Code hits /.well-known/oauth-authorization-server on the root origin
   → Server returns 404: "Route not found"
   → OAuth flow fails

Proof: the server works correctly

The same endpoint responds successfully when the Accept header is included:

# Initialize — succeeds with Accept header
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{
    "protocolVersion":"2024-11-05",
    "capabilities":{},
    "clientInfo":{"name":"test","version":"1.0"}
  }}' \
  http://127.0.0.1:29979/mcp
# → 200 OK, mcp-session-id header, valid SSE response with server capabilities

# Initialize — fails WITHOUT Accept header
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{
    "protocolVersion":"2024-11-05",
    "capabilities":{},
    "clientInfo":{"name":"test","version":"1.0"}
  }}' \
  http://127.0.0.1:29979/mcp
# → 406 Not Acceptable: "Client must accept both application/json and text/event-stream"

User workaround

Adding the header explicitly in the MCP config fixes the issue:

{
  "mcpServers": {
    "paper": {
      "type": "http",
      "url": "http://127.0.0.1:29979/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

This confirms the header is the only missing piece — all 20 Paper tools load correctly with it.

Suggested fix

In the Streamable HTTP transport client, ensure all requests include:

Accept: application/json, text/event-stream

This is required by the MCP spec and should be set automatically, not rely on user config. Servers like Stripe and Context7 happen to be lenient about the missing header, but spec-compliant servers like Paper enforce it.

Additionally, consider surfacing the actual HTTP error (406 + error body) rather than silently falling back to an auth prompt when connection fails for non-auth reasons.

Steps to reproduce

1. Install Paper Desktop (starts MCP server on port 29979)
2. Add to .mcp.json:

``json
"paper": {
"type": "http",
"url": "http://127.0.0.1:29979/mcp"
}
``

1. Start Claude Code
2. Paper appears as "requires authentication" instead of connected
3. Adding "headers": {"Accept": "application/json, text/event-stream"} to the config resolves it