MCP gateway exits on SSE disconnect instead of reconnecting (Claude Code integration)

[antixiris]

Summary

The MCP stdio gateway (gateway.py) terminates the entire process when the internal SSE connection to PiecesOS drops, instead of attempting to reconnect. This causes Claude Code (and likely other MCP clients) to lose the Pieces integration entirely until the next session restart.

Environment

• PiecesOS: 12.3.10
• CLI: 1.20.1 (latest via pipx)
• Platform: macOS 26.3.1 (Apple Silicon, Mac14,9)
• MCP Client: Claude Code (claude-ai v0.1.0)
• Config: pieces --ignore-onboarding mcp start (official setup via pieces mcp setup claude_code)

Reproduction

The issue occurs reliably after variable periods (10–55 minutes of idle/active usage). Steps:

1. Start Claude Code with Pieces MCP configured
2. MCP gateway connects successfully (tools discovered, LTM available)
3. Wait 10–55 minutes
4. Gateway SSE connection to PiecesOS drops silently
5. The CLI MCP process exits
6. Claude Code logs: Server disconnected / Client transport closed
7. All Pieces tools become permanently unavailable for the rest of the session

Log evidence

From ~/Library/Logs/Claude/mcp-server-Pieces.log:

2026-04-03T07:28:25.184Z [Pieces] [info] Message from server: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}
2026-04-03T07:38:34.235Z [Pieces] [info] Server transport closed
2026-04-03T07:38:34.236Z [Pieces] [info] Server transport closed unexpectedly, this is likely due to the process exiting early.
2026-04-03T07:38:34.236Z [Pieces] [error] Server disconnected.
2026-04-03T07:38:34.237Z [Pieces] [info] Client transport closed

Repeated pattern over 3 days:

Session start	Disconnect	Duration	Type
2026-04-01 08:28	08:44	16 min	Unexpected exit
2026-04-01 23:36	2026-04-02 14:45	~15h	Intentional shutdown (OK)
2026-04-02 14:45	15:40	55 min	Unexpected exit
2026-04-03 07:28	07:38	10 min	Unexpected exit

Additional: PiecesOS SIGABRT crash

PiecesOS also crashed with SIGABRT (Abort trap: 6) on 2026-04-02 01:26:27, after ~5 days of uptime (launched 2026-03-28). Crash report available in ~/Library/Logs/DiagnosticReports/Pieces OS-2026-04-02-012627.ips. At the time of the crash, PiecesOS was consuming ~2.6 GB RAM and ~37% CPU, suggesting possible memory accumulation over long uptimes.

Root cause analysis

Looking at gateway.py, the architecture is:

Claude Code ↔ stdio ↔ MCPGateway (Python) ↔ SSE ↔ PiecesOS (port 39300)

The _connection_handler method (line 329) handles SSE timeouts/errors gracefully by returning (not raising), but once it returns, the finally block runs _cleanup_stale_session() and the connection task completes. The MCPGateway.run() method (line 685) then has no reconnection loop — the stdio server just runs once and exits when the upstream connection is gone.

The call_tool method does call await self.connect() which can reconnect, but if no tool call happens after the SSE drop, the gateway process simply dies.

Suggested fix: Add a reconnection loop in MCPGateway.run() or in _connection_handler that monitors the SSE connection health and re-establishes it when it drops, rather than exiting the entire process.

Relation to existing work

This appears to be exactly what #441 ("harden gateway connection stability") addresses. Merging that PR would likely fix this issue. This report adds concrete reproduction data and logs.

Workaround

Restarting PiecesOS (pieces open after quit) clears accumulated memory (2.6 GB → 565 MB) and temporarily stabilizes connections. However, the MCP process will eventually disconnect again.