HP_TIMEOUT_CLIENT=30s too short for persistent MCP SSE streams — causes session termination

[marten-lucas]

Summary

The HaRP proxy deployed by Nextcloud AIO ships with HP_TIMEOUT_CLIENT=30s. This timeout is too short for persistent MCP sessions (MCP Streamable HTTP, protocol version 2025-03-26), causing any stateful MCP client session to be terminated after ~30 seconds of the GET stream being idle.

Steps to Reproduce

1. Install context_agent on Nextcloud AIO with HaRP enabled
2. Connect a MCP client using Streamable HTTP with persistent sessions (stateless_http=False)
3. Client opens a persistent GET SSE stream (server→client push channel) after initialize
4. After ~30 seconds of no activity on the GET stream, HaRP closes the connection
5. The server's StreamableHTTPServerTransport detects the closed stream and calls terminate()
6. Client receives McpError: Session terminated on the next keepalive ping or request
7. Client reconnects — loop repeats indefinitely

Root Cause

HaRP's HP_TIMEOUT_CLIENT=30s applies to the entire client-side HTTP connection, including long-lived SSE streams. The MCP Streamable HTTP protocol requires a persistent GET SSE stream for server→client push messages. This stream is intentionally idle (no data flows unless the server pushes) — but HaRP's client timeout doesn't distinguish between a truly idle connection and a healthy long-lived SSE stream.

HP_TIMEOUT_CLIENT=30s   # closes any client connection after 30s idle
HP_TIMEOUT_SERVER=1800s # server-side correctly set to 30 minutes

The asymmetry between client (30s) and server (1800s) timeouts is the issue.

Observed in Logs

Container logs (nc_app_context_agent):

Created new transport with session ID: 9d7d0dc8...
Terminating session: 9d7d0dc8...   ← after exactly ~12s (HaRP closes the GET stream)

Hermes Agent logs:

MCP server 'Nextcloud' keepalive failed, triggering reconnect (state: connected → degraded): McpError: Session terminated

Expected Behavior

HP_TIMEOUT_CLIENT should be set to a value that accommodates long-lived SSE streams, e.g. 600s or higher. Alternatively, AIO documentation should note that MCP clients require an increased HP_TIMEOUT_CLIENT.

Suggested Fix

Increase the default HP_TIMEOUT_CLIENT for AIO HaRP deployments:

HP_TIMEOUT_CLIENT=600s  # 10 minutes — accommodates MCP SSE streams

Or expose HP_TIMEOUT_CLIENT as a configurable AIO environment variable so administrators can set it without recreating the HaRP container manually.

Workaround

Recreate the nextcloud-aio-harp container manually with HP_TIMEOUT_CLIENT=600s. This override is lost on every AIO update.

Environment

• Nextcloud AIO: latest (Nextcloud 33.0.7)
• HaRP: ghcr.io/nextcloud/nextcloud-appapi-harp:release
• Default HP_TIMEOUT_CLIENT=30s
• MCP client: any client using Streamable HTTP persistent sessions (Hermes Agent, Claude Code, etc.)

Relation

This issue is a companion to nextcloud/context_agent#227 — even when that issue is fixed (stateless_http=False), persistent MCP sessions will still fail unless this timeout is also addressed.

[oleksandr-nc]

Hello. Thank you for reporting this - we will start investigation on this matter, asap

[oleksandr-nc]

@marten-lucas , if you recreate container with HP_TIMEOUT_CLIENT=600s or 1800s does that help in this case?

I have suspicions that increasing the HP_TIMEOUT_CLIENT will not help and the diagnosis is not fully correct.