Remote MCP servers using Server-Sent Events (SSE) fail to start with 'UnknownError Server error' #834

Issue Description

Remote MCP servers that use Server-Sent Events (SSE) transport fail to start in opencode with the error "MCP server failed to start name=UnknownError Server error", even when the server responds correctly to direct HTTP requests.

Steps to Reproduce

1. Configure a remote MCP server that uses SSE transport in ~/.config/opencode/config.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "microsoft-docs": {
      "type": "remote",
      "url": "https://learn.microsoft.com/api/mcp",
      "enabled": true
    }
  }
}

2. Start opencode
3. Check logs at ~/.local/share/opencode/log/

Expected Behavior

The remote MCP server should connect successfully and make its tools available in opencode.

Actual Behavior

• opencode logs show: service=mcp key=microsoft-docs type=remote found
• Followed by: ERROR ... service=tui message=MCP server microsoft-docs failed to start name=UnknownError Server error
• Tools from the MCP server are not available

Technical Analysis

Server Requirements (Working)

The Microsoft Docs MCP server correctly implements SSE transport:

# Test SSE protocol requirements
curl -X POST "https://learn.microsoft.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

Response (working correctly):

event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"logging":{},"tools":{"listChanged":true}},"serverInfo":{"name":"Learn.MCP.API","version":"1.0.0.0"}},"id":1,"jsonrpc":"2.0"}

Client Requirements (Issue)

The server requires:

1. Accept header: application/json, text/event-stream
2. Response handling: SSE format with event: message and data: fields
3. Protocol compliance: Proper MCP handshake with clientInfo

Without the correct Accept headers, the server returns:

{"error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":"","jsonrpc":"2.0"}

Environment

• opencode version: 0.2.21
• OS: Linux
• MCP server: Microsoft Learn Docs API (https://learn.microsoft.com/api/mcp)
• Server transport: Server-Sent Events (SSE)

Root Cause

opencode's remote MCP client implementation appears to not support SSE-based MCP servers. The client likely:

1. Does not send the required Accept: application/json, text/event-stream headers
2. Cannot handle SSE response format (event: message / data: structure)
3. May not implement the SSE transport layer of the MCP specification

Related

• Issue MCP server failed to start (unstable MCP servers) #829 discusses unstable MCP connections but for different reasons
• SSE transport is part of the official MCP specification for web compatibility
• Other MCP clients (VS Code) may have better SSE support

Suggested Solution

Implement SSE transport support in opencode's remote MCP client to handle:

• Proper Accept headers for SSE endpoints
• SSE response parsing (event: and data: fields)
• Long-lived SSE connections with proper error handling

This would enable compatibility with Microsoft's official MCP server and other SSE-based MCP implementations.