capture_live_filter/set_enabled timeout cascades and crashes entire MCP server

[danbao]

Problem Description

When capture_live_filter or capture_live_set_enabled times out, the timeout cascades and crashes the entire MCP server connection. Subsequent calls to unrelated tools (e.g., collection_list) also fail with "MCP server unreachable".

Critical finding: This also reproduces with 0 records after a full app restart — the issue is not solely caused by large record sets.

Root Cause Analysis

From the source code in lib/api/client.dart:

_httpClient.connectionTimeout = const Duration(seconds: 5);

The ReqableApiClient only sets connectionTimeout (5s) but does not set any read/response timeout on the HttpClient. This means:

1. When Reqable's local API is slow or stuck, the HTTP request hangs indefinitely
2. The MCP server blocks on the await in _send() and cannot process any other requests
3. The MCP host (e.g., Hermes, Claude Desktop) has its own timeout (typically 30-300s), after which it marks the entire MCP server as "unreachable"
4. Since the MCP server is stuck on the hung request, all subsequent tool calls fail — even unrelated ones

Steps to Reproduce

Scenario A: Large record set

1. Connect to Reqable MCP server via stdio
2. Start live capture in Reqable and accumulate 3000+ records
3. Call capture_live_filter with any filter
4. After timeout, try calling any other tool (e.g., collection_list)
5. Result: All subsequent calls fail with "MCP server unreachable" for ~45-50 seconds

Scenario B: Clean restart (0 records)

1. Fully quit and restart the Reqable app (clear all records)
2. Reconnect MCP (hermes mcp test reqable → success, 46 tools)
3. Call capture_live_filter(filters: []) (empty filter, 0 records)
4. Still times out at 300s, then cascades to crash the entire MCP connection

Additional Observations

• capture_live_set_enabled(true) also hangs when Reqable is processing heavy traffic
• The cascading failure means a single slow live capture operation can take down the entire MCP server for all tool categories (collections, REST, scripts, etc.)
• Restarting the Reqable app does NOT reliably fix the issue — the local API server may enter a persistent bad state
• hermes mcp test reqable succeeds (46 tools discovered, ~150ms), confirming stdio transport is healthy; the hang is in the Reqable local API layer

Possible Causes (beyond missing timeout)

• Reqable's local API server enters a bad state after the first timeout and doesn't recover on app restart (stale socket/lock)
• The MCP server's HttpClient keeps a persistent connection that becomes stale
• A Reqable-side lock/mutex is not released after an interrupted request

Suggested Fix

Add a request-level timeout to the HttpClient in ReqableApiClient:

_httpClient.connectionTimeout = const Duration(seconds: 5);
_httpClient.idleTimeout = const Duration(seconds: 30); // or configurable

Or wrap the _send() method with a timeout:

Future<String> _send(String method, Request req) async {
  // ... existing code ...
  return await _doSend(method, req).timeout(
    const Duration(seconds: 30),
    onTimeout: () => throw TimeoutException('Request to ${req.route} timed out'),
  );
}

This would prevent a single slow request from blocking the entire MCP server.

Environment

• macOS 15 (Apple Silicon)
• Reqable MCP Server (latest, stdio transport)
• Reqable App (latest)
• MCP Host: Hermes Agent

[danbao]

Update: Reproduced with a clean slate — zero records after a full Reqable app restart. The issue is not solely caused by large record sets.

Steps:

1. Fully quit and restart the Reqable app
2. Reconnect MCP (hermes mcp test reqable → success, 46 tools)
3. Call capture_live_filter(filters: []) (empty filter, 0 records)
4. Still times out at 300s, then cascades to crash the entire MCP connection

This suggests the problem is in the Reqable local API server itself — the /capture/live/filter and /capture/live/on endpoints may hang even when there's nothing to process. Possible causes:

• Reqable's local API server enters a bad state after the first timeout and doesn't recover properly on app restart (e.g., stale socket/lock)
• The MCP server's HttpClient keeps a persistent connection that becomes stale after a timeout, and Reqable doesn't properly reset it
• There may be a Reqable-side lock/mutex that isn't released after an interrupted request

[danbao]

Update: Found a related issue in reqable-app: reqable/reqable-app#2742

更新勾选自动结束进程后只会关闭 Reqable 主程序，MCP 服务是独立进程不会被关闭。MCP 进程占用程序文件，安装界面无任何提示、进度停滞，手动结束 MCP 进程后安装才会继续。

This confirms that the MCP server is a separate process from the Reqable app. This likely explains our timeout issue:

1. MCP server process (/Applications/Reqable.app/Contents/Helpers/mcp-server) runs independently
2. When Reqable app restarts, the MCP server process may not be restarted, holding stale HTTP connections to Reqable's local API
3. The stale connections cause all subsequent API calls (including /capture/live/filter and /capture/live/on) to hang indefinitely
4. Since there's no request-level timeout in ReqableApiClient._send(), the hang blocks the entire MCP server

Workaround (confirmed working): After restarting Reqable, also kill the old MCP server process:

pkill -f "mcp-server"

Then restart the MCP connection from the host.

This also aligns with the fix suggestion — adding a timeout to _send() would handle stale connections gracefully without requiring manual process cleanup.

[danbao]

Update 2: After pkill -f "mcp-server" + Reqable restart, tested again:

1. hermes mcp test reqable → ✅ Connected (152ms), 46 tools
2. capture_live_set_enabled(true) → ❌ ClosedResourceError() (immediate, not timeout)
3. After this error, all subsequent calls fail — even collection_list and capture_breakpoint_get_config timeout at 300s

This confirms the cascading failure is even worse than initially reported:

• The ClosedResourceError from capture_live_set_enabled corrupts the MCP server state
• The server becomes completely unresponsive to ALL tool calls, not just live capture tools
• Only killing the MCP process and restarting Reqable can recover

Root cause hypothesis: When capture_live_set_enabled calls GET /capture/live/on, the Reqable local API may close/reset the connection (e.g., if capture is already active, or if there's a state conflict). The MCP server's HttpClient doesn't handle this gracefully — the closed connection leaks into the Dart event loop and blocks all subsequent HTTP requests.

The fix should include both:

1. Request-level timeouts (as suggested above)
2. Connection error isolation — a failed request on one tool should not affect other tools
3. Proper connection cleanup on IOException / ClosedResourceError