anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-23 02:36:57 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

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

New Issue
Closed
opened 2026-02-16 17:27:32 -05:00 by yindo · 3 comments
yindo commented 2026-02-16 17:27:32 -05:00
Owner
Copy Link
Copy Source

Originally created by @FBakkensen on GitHub (Jul 10, 2025).

Originally assigned to: @thdxr on GitHub.

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
    }
  }
}
  1. Start opencode
  2. 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

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 #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.

Originally created by @FBakkensen on GitHub (Jul 10, 2025). Originally assigned to: @thdxr on GitHub. ## 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`: ```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: ```bash # 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: ```json {"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 #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.
yindo closed this issue 2026-02-16 17:27:32 -05:00
yindo commented 2026-02-16 17:27:32 -05:00
Author
Owner
Copy Link
Copy Source

@hinate13 commented on GitHub (Jul 23, 2025):

I wonder if this is the same issue with context7 as well? Per context7 doc, I use this:

  "mcp": {
    "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "enabled": true
    },

If you access the url above in your browser, it shows the streaming requirement:

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

And in the opencode logs, i see this:

ERROR 2025-07-23T04:29:37 +0ms service=tui message=MCP server context7 failed to start name=UnknownError Server error

Opencode works if I change the config to local using npx variant:

"context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"],
      "enabled": true
      },

Robustness Recommendation:
It would be nice if it fails on one MCP, it doesn't crash all the MCP? I had additional MCP servers on local, and OC thinks I have no tools available when context7 remote failed.

@hinate13 commented on GitHub (Jul 23, 2025): I wonder if this is the same issue with context7 as well? Per context7 doc, I use this: ``` "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "enabled": true }, ``` If you access the url above in your browser, it shows the streaming requirement: ``` {"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept text/event-stream"},"id":null} ``` And in the opencode logs, i see this: ``` ERROR 2025-07-23T04:29:37 +0ms service=tui message=MCP server context7 failed to start name=UnknownError Server error ``` Opencode works if I change the config to local using npx variant: ``` "context7": { "type": "local", "command": ["npx", "-y", "@upstash/context7-mcp"], "enabled": true }, ``` **Robustness Recommendation:** It would be nice if it fails on one MCP, it doesn't crash all the MCP? I had additional MCP servers on local, and OC thinks I have no tools available when context7 remote failed.
yindo commented 2026-02-16 17:27:32 -05:00
Author
Owner
Copy Link
Copy Source

@edwardwu commented on GitHub (Jul 23, 2025):

For conext7, I changed the opencode.json to use /sse endpoint for remote mcp server, then it seems working fine.

Context7 (Documentation):

• context7_resolve-library-id - Resolves package names to Context7-compatible library IDs
• context7_get-library-docs - Fetches up-to-date documentation for libraries

"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/sse",
"enabled": true
},

@edwardwu commented on GitHub (Jul 23, 2025): For conext7, I changed the opencode.json to use /sse endpoint for remote mcp server, then it seems working fine. Context7 (Documentation): • context7_resolve-library-id - Resolves package names to Context7-compatible library IDs • context7_get-library-docs - Fetches up-to-date documentation for libraries "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/sse", "enabled": true },
yindo commented 2026-02-16 17:27:32 -05:00
Author
Owner
Copy Link
Copy Source

@thdxr commented on GitHub (Jul 25, 2025):

fixed in latest

@thdxr commented on GitHub (Jul 25, 2025): fixed in latest
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#598
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?