Feature Request: First-class HTTP/SSE MCP transport for local-network servers

Summary

OpenCode's type: "remote" already connects to remote MCP servers over HTTP, but the experience for local-network MCP servers — like a Raspberry Pi running a RAG server on your LAN — is undocumented, fragile, and locked to the deprecated SSE transport. This feature request proposes explicit, first-class support for connecting to MCP servers over HTTP/SSE on the local network with clear configuration, plain-HTTP tolerance, and Streamable HTTP compatibility.

Motivation: the Raspberry Pi LAN use case

I run an MCP server on a Raspberry Pi 4 (192.168.2.125:8082) on my home network. It exposes semantic search tools (search_library, list_sources) over HTTP/SSE. I want my laptop running OpenCode to use those tools — without SSH tunnels, without running a second copy locally, and without hacks.

The server implements the standard MCP SSE transport (Python mcp.server.sse.SseServerTransport):

• GET http://192.168.2.125:8082/sse — SSE event stream
• POST http://192.168.2.125:8082/messages/ — JSON-RPC messages

This is a textbook MCP-over-HTTP deployment. Everything should "just work."

What works today

OpenCode does have type: "remote" for HTTP-based MCP servers:

// opencode.json
{
  "mcp": {
    "rag-library": {
      "type": "remote",
      "url": "http://192.168.2.125:8082/sse",
      "enabled": true
    }
  }
}

And opencode mcp add --url exists in the CLI. That's good — the bones are there.

What's missing / broken for this use case

1. SSE is deprecated; Streamable HTTP is the present

The MCP specification deprecated SSE in March 2025 (spec version 2025-03-26) in favor of Streamable HTTP. New MCP servers — and increasingly existing ones — use Streamable HTTP. OpenCode's type: "remote" only speaks SSE (confirmed by issue #8058).

For local-network servers this is doubly painful: the Python MCP SDK's SseServerTransport is the old transport, but alternatives like streamable_http from the same SDK are already available. OpenCode should support both so users aren't stuck on a deprecated protocol.

2. Plain HTTP on the LAN is treated as second-class

The docs show https:// URLs exclusively. Local-network servers on http:// (no TLS) are a legitimate deployment pattern — not everything needs a CA-signed cert on a home LAN. If OpenCode rejects, warns, or behaves differently with http:// URLs, that creates unnecessary friction.

Specific concerns:

• Does the SSE client require HTTPS?
• Are there CORS or mixed-content checks that fail on plain HTTP?
• Is localhost / 127.0.0.1 treated differently from 192.168.x.x?

3. Known SSE reliability issues

OpenCode has several open issues about SSE transport hangs, malformed stream handling, and connection wedging (e.g., #8406, #17168, #834). For a LAN MCP server that may be behind Wi-Fi latency or a slow Pi, these bugs make the feature unreliable in practice.

4. No explicit transport selection

There's no way to say "I want this server via SSE" vs "I want Streamable HTTP." The transport is inferred from the type field (remote = SSE, and there's no type: "http" or type: "sse"). A transport field would let users be explicit:

{
  "mcp": {
    "rag-library": {
      "type": "remote",
      "transport": "sse",          // or "streamable-http"
      "url": "http://192.168.2.125:8082/sse",
      "headers": {
        "X-API-Key": "{env:RAG_MCP_KEY}"
      }
    }
  }
}

5. Discovery / documentation gap

The words "local network," "LAN," "Raspberry Pi," and "SSE" don't appear in the MCP servers documentation. A user with a Pi on their network has to guess that type: "remote" is the right config key. A short example showing a 192.168.x.x URL would go a long way.

Proposed solution

1. Add a transport field to remote MCP server config:

   • "sse" — classic SSE (GET /sse + POST /messages)
   • "streamable-http" — current MCP spec Streamable HTTP
   • Default: auto-detect (attempt Streamable HTTP first, fall back to SSE)

2. First-class plain-HTTP support — http:// URLs on RFC 1918 addresses (192.168.x.x, 10.x.x.x, 172.16-31.x.x) and localhost should work without TLS warnings or restrictions.

3. Fix SSE transport reliability — address the hangs, content-type checks, and connection lifecycle issues tracked in the existing SSE bugs.

4. Add a LAN example to the docs:

   {
     "mcp": {
       "pi-rag": {
         "type": "remote",
         "transport": "sse",
         "url": "http://192.168.2.125:8082/sse",
         "enabled": true,
         "timeout": 10000
       }
     }
   }

5. Optional headers for API keys — already supported per the docs, but worth calling out for LAN servers that may want a simple shared-secret auth.

Config format reference

Security considerations

• Local network only by default — http:// URLs on private IP ranges are inherently LAN-scoped. OpenCode could add a confirmation prompt the first time it connects to a non-localhost http:// URL.
• API key header support — already exists via headers, which is sufficient for LAN shared-secret auth.
• No mTLS required for LAN — requiring TLS on a home network adds friction without meaningful security benefit when traffic never leaves the LAN.
• mTLS optional for advanced users — could be added later via tls config block.

How other tools handle this

Environment

• OpenCode version: 1.17.18 (CLI, Linux ARM64 on Raspberry Pi 4)
• MCP server: Python mcp.server.sse.SseServerTransport on port 8082
• Network: LAN, 192.168.2.0/24, plain HTTP

Related issues

• #8058 — Add HTTP Streamable transport (closed)
• #6242 — Remote MCP should negotiate HTTP/Streamable before deprecated SSE
• #5371 — Support non-standard SSE handshakes
• #8406 — Connection hangs with non-standard SSE/HTTP servers
• #17168 — Remote MCP servers fail with "Invalid content type"
• #834 — Remote MCP servers using SSE fail to connect