Skip to content
satware® AI OnlyOffice MCP

HTTP Transport Setup

When to Use HTTP

Section titled “When to Use HTTP”

Use HTTP transport when connecting to a running server over the network.

Client Config Format Notes
opencode mcp key + type: "remote" Different from Claude Desktop format
Claude Desktop (newer) mcpServers + url field Older builds need STDIO
TypingMind Via proxy url mode in typingmind-mcp
Custom clients Raw JSON-RPC over HTTP See smoke test below

The HTTP server is a single Express app on port 3847 serving /mcp, /admin, /artifacts, /health, /instances. MCP protocol version: 2025-11-25.

Prerequisites

Section titled “Prerequisites”
  • A running MCP server at http(s)://<host>:3847
  • TLS termination (Caddy/Nginx in production, mkcert for local dev)
  • Verify: curl -f <url>/health returns {"status":"healthy"}

Client Configuration

Section titled “Client Configuration”

  1. opencode (uses mcp key, NOT mcpServers)

    ~/.config/opencode/opencode.jsonc
    {
      "mcp": {
        "onlyoffice": {
          "type": "remote",
          "url": "https://onlyoffice.localhost/mcp"
        }
      }
    }

    Or via CLI:

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

    Verify: opencode mcp list should show onlyoffice connected.

  2. Claude Desktop / Cline (remote URL form)

    {
      "mcpServers": {
        "onlyoffice": {
          "url": "https://onlyoffice.localhost/mcp"
        }
      }
    }

    Older Claude Desktop builds only support STDIO command/args. Use the STDIO Setup Guide for those.

  3. TypingMind via proxy (url mode)

    Terminal window
    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"
          }
        }
      }'

  4. Raw JSON-RPC smoke test (curl)

    Terminal window
    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"}
        }
      }'

    Response is text/event-stream with the server’s protocolVersion, capabilities, and serverInfo. A mcp-session-id header is returned for subsequent requests in the same session.

TLS Trust (Local Dev)

Section titled “TLS Trust (Local Dev)”

Local dev uses https://onlyoffice.localhost with a certificate from mkcert (local CA). Connections fail with x509: certificate signed by unknown authority on machines that don’t trust the mkcert root.

Scenario Fix
Same host (where mkcert ran) Already trusted
Other LAN machine mkcert -install + copy $(mkcert -CAROOT)/rootCA-*.pem
CI runner Trust CA via update-ca-certificates (Debian)

Production uses real certs (Let’s Encrypt via Caddy) — no mkcert.

Troubleshooting

Section titled “Troubleshooting”
Issue Cause Fix
opencode mcp list shows disconnected TLS not trusted or server down curl <url>/health first; install mkcert CA
Client sends mcpServers to opencode Wrong format Use mcp key + type: "remote"
HTTP 500 on second initialize Fixed in v1.1.0 (fresh McpServer per session) Update to >= 1.1.0
426 Upgrade Required Legacy SSE transport Use Streamable HTTP (POST + Accept: text/event-stream)
Works locally, fails remotely Firewall or no TLS Reverse proxy on :443
Section titled “Related”