opencode serve: local stdio MCP connection silently dropped mid-session — tools become permanently unavailable #38266

Summary

Local stdio MCP servers (specifically serena-agent) work initially in opencode serve + opencode attach mode, but silently lose their connection after some tool calls. The MCP server process stays alive, no error is logged in the MCP server's logs — the tool execution itself completes in <20ms — but the opencode server-side MCP client has already dropped the connection, causing subsequent tool calls to time out.

Reproduction

1. Start opencode in serve mode: opencode serve --port 4096
2. Attach a session: opencode attach http://127.0.0.1:4096
3. Verify serena MCP server is configured and appears connected
4. Use serena_create_text_file or other serena tools successfully (they work)
5. After some period or number of tool calls, serena tools become unavailable
6. The serena process remains running (ps aux shows the process alive with same PID)
7. The user sees: Model tried to call unavailable tool 'serena_create_text_file' or tool calls time out
8. The serena MCP logs (~/.serena/logs/) show the tool completed successfully with zero errors

Evidence

• serena-side: All create_text_file calls complete in <20ms. Zero timeout errors in serena logs across all sessions.
• Process state: Multiple serena processes remain running (ps aux | grep serena) — they never crashed.
• Tool availability: serena tools ARE available at session start (initial serena_read_file, serena_get_symbols_overview calls succeed), then BECOME unavailable later.
• No serena-side error: The disconnect is invisible to serena — it never knows the client dropped the connection.

# serena log showing successful execution:
INFO  2026-07-22 08:44:58,683 [MainThread] mcp.server.lowlevel.server:_handle_request - Processing request of type CallToolRequest
INFO  2026-07-22 08:44:58,724 [SerenaAgentTaskExecutor] serena.task_executor:_process_task_queue - Starting execution of Task-44:CreateTextFileTool
INFO  2026-07-22 08:44:58,728 [Task-44:CreateTextFileTool] serena.tools.tools_base:task - Result: File created: tests/test_doi_routes.py.
INFO  2026-07-22 08:44:58,729 [Task-44:CreateTextFileTool] serena.task_executor:stop - Task-44:CreateTextFileTool completed in 0.004 seconds

Root Cause Analysis

The serena MCP tool execution itself is fast (<20ms) and never errors. The problem is at the opencode server's MCP transport layer in serve mode:

1. The opencode serve daemon spawns a serena process per session and communicates via stdio
2. The MCP client (in packages/opencode/src/mcp/index.ts) calls client.listTools() on every LLM step via resolveTools() (as documented in Bug: MCP tools permanently lost mid-session after single transient listTools() failure — no retry, no reconnect #17099)
3. A transient listTools() failure (e.g., pipe hiccup, GC pause, timing issue) triggers the catch handler which permanently deletes the MCP client from state.clients
4. Once deleted, the client is never recreated — the serena process stays alive but the opencode server has no reference to it
5. In opencode serve mode, this eviction affects ALL attached sessions (they share the server's MCP state)
6. The timeout field in McpLocalConfig only covers the initial handshake, not ongoing per-request calls

The --project-from-cwd flag also means each serena process independently auto-detects the project and starts LSP servers, which adds startup time that makes the initial listTools() more likely to hit timeouts.

Related Issues

• Bug: MCP tools permanently lost mid-session after single transient listTools() failure — no retry, no reconnect #17099 (CLOSED): MCP tools permanently lost mid-session after single transient listTools() failure — same root cause (delete on transient failure), but the fix may not cover serve mode where the MCP state is shared
• MCP remote client has no transport-level retry on socket/connection errors #25287 (OPEN): MCP remote client has no transport-level retry on socket/connection errors — same missing retry pattern, but focuses on remote HTTP transport, not local stdio in serve mode
• Session hangs indefinitely after MCP tool-call — no timeout recovery (deadlock) #35207 (OPEN): Session hangs indefinitely after MCP tool-call — no timeout recovery (deadlock) — related symptom of MCP calls that never return
• MCP transport stays 'failed' after a transient connection close — plugin tools disappear for the rest of the session #38088 (CLOSED): MCP transport stays 'failed' after a transient connection close — plugin tools disappear — same symptom, closed as duplicate of MCP remote client has no transport-level retry on socket/connection errors #25287
• fix(mcp): MCP server loses connection mid-session causing intermittent failures #23997 (CLOSED): fix(mcp): MCP server loses connection mid-session — related fix

Environment

• opencode version: 1.18.4
• Mode: opencode serve on port 4096 + opencode attach
• MCP server: serena-agent 1.2.0 (Python FastMCP, stdio transport)
• OS: Linux (Debian)