HTTP-Transporteinrichtung

Wann HTTP verwendet wird

Verwenden Sie HTTP-Transport, wenn Sie sich über das Netzwerk mit einem laufenden Server verbinden.

Client	Konfigurationsformat	Hinweise
opencode	`mcp`-Schlüssel + `type: "remote"`	Anders als das Claude-Desktop-Format
Claude Desktop (neuer)	`mcpServers` + `url`-Feld	Ältere Builds benötigen STDIO
TypingMind	Über Proxy	`url`-Modus in typingmind-mcp
Eigene Clients	Raw-JSON-RPC über HTTP	Siehe Smoke-Test unten

Der HTTP-Server ist eine einzelne Express-App auf Port 3847, die /mcp, /admin, /artifacts, /health, /instances bedient. MCP-Protokollversion: 2025-11-25.

Voraussetzungen

Ein laufender MCP-Server unter http(s)://<host>:3847
TLS-Terminierung (Caddy/Nginx in Produktion, mkcert für lokale Entwicklung)
Überprüfen: curl -f <url>/health gibt {"status":"healthy"} zurück

Client-Konfiguration

opencode (verwendet mcp-Schlüssel, NICHT mcpServers)

{
  "mcp": {
    "onlyoffice": {
      "type": "remote",
      "url": "https://onlyoffice.localhost/mcp"
    }
  }
}

Oder über CLI:

opencode mcp add onlyoffice --url "https://onlyoffice.localhost/mcp"

Überprüfen: opencode mcp list sollte onlyoffice connected anzeigen.

Claude Desktop / Cline (Remote-URL-Form)
```
{
  "mcpServers": {
    "onlyoffice": {
      "url": "https://onlyoffice.localhost/mcp"
    }
  }
}
```
Ältere Claude-Desktop-Builds unterstützen nur STDIO command/args. Verwenden Sie dafür den STDIO-Einrichtungsguide.

TypingMind über Proxy (URL-Modus)

curl -X POST http://localhost:50880/start \
  -H "Authorization: Bearer <proxy-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServers": {
      "onlyoffice": {
        "url": "https://onlyoffice.localhost/mcp"
      }
    }
  }'

Raw-JSON-RPC-Smoke-Test (curl)

curl -X POST https://onlyoffice.localhost/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {"name": "smoke-test", "version": "1.0"}
    }
  }'

Die Antwort ist text/event-stream mit der protocolVersion, capabilities und serverInfo des Servers. Ein mcp-session-id-Header wird für nachfolgende Anfragen derselben Sitzung zurückgegeben.

Falsch	Warum es fehlschlägt	Richtig
`"mcpServers"` in opencode	opencode ignoriert unbekannte Schlüssel auf oberster Ebene	`"mcp"`
Fehlendes `"type": "remote"`	opencode verwendet standardmäßig lokales stdio	`"type": "remote"` hinzufügen
`"url"` ohne Schema	URL-Parser lehnt nackten Host ab	`"https://..."`

TLS-Vertrauen (lokale Entwicklung)

Die lokale Entwicklung verwendet https://onlyoffice.localhost mit einem Zertifikat von mkcert (lokale CA). Verbindungen schlagen mit x509: certificate signed by unknown authority auf Maschinen fehl, die der mkcert-Root nicht vertrauen.

Szenario	Lösung
Derselbe Host (auf dem mkcert lief)	Bereits vertraut
Andere LAN-Maschine	`mkcert -install` + `$(mkcert -CAROOT)/rootCA-*.pem` kopieren
CI-Runner	CA über `update-ca-certificates` vertrauen (Debian)

Produktion verwendet echte Zertifikate (Let’s Encrypt via Caddy) - kein mkcert.

Fehlerbehebung

Problem	Ursache	Lösung
`opencode mcp list` zeigt getrennt	TLS nicht vertraut oder Server down	Zuerst `curl <url>/health`; mkcert CA installieren
Client sendet `mcpServers` an opencode	Falsches Format	`mcp`-Schlüssel + `type: "remote"` verwenden
HTTP 500 beim zweiten `initialize`	Behoben in v1.1.0 (frischer McpServer pro Sitzung)	Auf `>= 1.1.0` aktualisieren
`426 Upgrade Required`	Legacy-SSE-Transport	Streamable HTTP verwenden (`POST` + `Accept: text/event-stream`)
Funktioniert lokal, schlägt remote fehl	Firewall oder kein TLS	Reverse Proxy auf `:443`