Add configurable idle timeout for persistent named sessions

[0xdevalias]

Problem

Named @sessions are persistent: each keeps a bridge (and, for stdio, the MCP server child process) alive until the session is explicitly closed. This is useful for repeated calls, but it can leave one idle MCP process running for every consumer context.

One concrete use case is Codex skills that invoke an MCP server on demand through mcpc. Calls often arrive in short bursts, so keeping the connection warm briefly is useful; keeping one MCP process alive indefinitely for every Codex thread is not.

The existing --timeout is a per-request timeout, so this should use distinct terminology.

Proposed interface

mcpc connect <server> @session --idle-timeout 600

--idle-timeout is expressed in seconds and is persisted with the named session, like other connection settings that survive bridge restart/reconnect.

• Omission or --idle-timeout 0: preserve the current unlimited lifetime.
• A positive value: after that many seconds without user-issued MCP activity, gracefully close the MCP transport and any stdio server child process, then exit the bridge.
• Retain the named session and its configuration after idle shutdown. Mark it as intentionally idle/stopped rather than crashed so background crash recovery does not immediately restart it; the next user operation should start its bridge on demand.

Activity semantics

• Count user-issued MCP operations as activity, including an explicit user ping.
• Do not count internal keepalive/health pings, passive server notifications, notification-triggered cache refreshes or resource sync, or other housekeeping traffic.
• Never expire while one or more user operations are in flight. Once the last active operation completes, start a fresh idle period.

This likely needs a user-activity timestamp separate from lastSeenAt, because lastSeenAt currently records successful keepalive pings as well as commands.

Flag placement

connect seems like the natural public entry point because it creates/configures a named session, and the timeout belongs to that persisted session configuration. Restart and automatic reconnect should reuse the saved value without requiring the flag again. If there is a better internal configuration boundary, the important behavior is that the value is set when creating/configuring the named session and persists with it.

Suggested acceptance matrix

Case	Expected result
Flag omitted	Existing unlimited-lifetime behavior
--idle-timeout 0	Same unlimited-lifetime behavior
Positive timeout, no user activity	Transport and child process close gracefully after the timeout; named session remains available for on-demand reuse
User operation before deadline	Idle deadline resets after the operation completes
Operation runs past deadline	Session stays alive until the operation completes, then receives a fresh full idle period
Concurrent operations	Session cannot expire until all user operations have completed
Internal keepalive ping	Does not reset the idle deadline
Passive notification / housekeeping refresh	Does not reset the idle deadline
Explicit user ping	Does reset the idle deadline
Bridge restart/reconnect	Persisted timeout is retained
Next command after idle shutdown	Bridge/transport starts on demand and the command succeeds
HTTP and stdio transports	HTTP closes cleanly; stdio also terminates its server child process

---

Drafted by Codex (GPT 5.6 Sol Medium) at my request, and reviewed by me before posting

[jancurn]

Thanks for the suggestion - the idea makes sense, we'll add it soon

[0xdevalias]

the idea makes sense, we'll add it soon

@jancurn Amazing, thankyou!

[jancurn]

Design: --idle-timeout in the MCP 2026-07-28 era

We recently added support for MCP 2026-07-28 (stateless era: no handshake, no Mcp-Session-Id) while keeping the mcpc interface unchanged — named sessions, connect, a persistent bridge per session. Before implementing this issue we reviewed how it fits the new protocol and the upcoming --auto-restart (#312). Summary of the design we intend to implement:

Still makes sense — more than before

What an idle session wastes is mostly local: a bridge process per session, the stdio child where applicable, plus a 30s keepalive (ping on legacy connections, server/discover on 2026-07-28) hitting the server forever. The new protocol changes the cost of coming back, not the waste: stateless connections have nothing to resume or expire, so parking and lazily reconnecting is lossless; stateful ones (legacy protocol, or modern servers that issue a session id) would likely have their session idle-expired by the server anyway.

Core semantics: drop the connection, keep the session, wake fresh on demand

1. Idle shutdown = full release. When the timer fires (no user activity for the configured period, nothing in flight), the bridge terminates the MCP session properly (HTTP DELETE for stateful HTTP; graceful child shutdown for stdio), records a new idle session status, and exits. We deliberately do not park the session id for later resumption — most servers expire idle sessions anyway, so resume-on-wake would routinely fail into an error path. Terminating up front makes wake deterministic and actually frees server-side resources, which is the point.
2. Wake is lazy and always fresh. The next command targeting the session starts a new bridge with a fresh MCP session (like restart today) — no error, no manual step. For stateless servers this is indistinguishable from resumption; for stateful servers, session-state loss is the documented, opted-in cost (same caveat as --auto-restart).
3. Background probes never wake idle sessions. idle is an intentional state, unlike crashed: mcpc / mcpc grep won't resurrect it in the background — otherwise periodic discovery would keep every session hot and defeat the feature.

Keeping mcpc grep useful

So progressive tool discovery doesn't go blind on parked sessions: at idle shutdown the bridge persists its tools cache (+ server instructions) to a per-session snapshot on disk. Global mcpc grep searches the snapshot without waking the session and badges those matches as coming from an idle session. Session-targeted commands (mcpc @s grep, mcpc @s tools-list, …) wake it and use live data.

Interplay with --auto-restart (#312)

Orthogonal and composable: --auto-restart recovers from server-initiated expiry during the session's active life; --idle-timeout is client-initiated release after inactivity. One unification: when the server expires the session while an idle timeout is configured and nothing is in flight, the bridge records idle rather than expired — the server just beat our timer to the same outcome, and wake-fresh recovery is identical. This also avoids churn where auto-restart would background-resurrect a session nobody is using, only for the idle timer to kill it again.

Activity semantics (as proposed here, confirmed)

• Counts: user-issued MCP operations from the CLI (incl. an explicit ping) and --proxy traffic.
• Doesn't count: internal 30s keepalives, server notifications, notification-triggered cache refresh / resource re-sync.
• Never fires while operations are in flight; a fresh full period starts after the last one completes.
• Deferred while the session has active resource subscriptions (a live file-sync contract) or pending async tasks (tied to the server-side session on the legacy protocol — idling out would orphan their results), and while --proxy clients hold open sessions (proxy clients can't wake an idle bridge, so combining the flags will print a warning).

Flag shape as proposed: mcpc connect <server> @s --idle-timeout <secs>, persisted with the session config (also idleTimeoutSecs in mcp.json entries), 0/omitted = current unlimited behavior, survives restarts and reconnects.

---

Generated by Claude Code

[jancurn]

Implementation notes

Follow-up to the design above — the concrete plan for the implementation PR (worked out against the current codebase and #312's branch; assumes #312 merges first).

Flag & persistence

• --idle-timeout <secs> on connect (single and bulk), validated as a non-negative integer.
• Persisted as idleTimeoutSecs on ServerConfig (src/lib/types.ts), mirroring the existing timeout field. This makes everything flow for free: SessionData.server is a ServerConfig, so it lands in sessions.json; startBridge() serializes the server config into the bridge argv; restartBridge() rebuilds it from session.server, so restarts and background reconnects retain the value; and mcp.json config entries get an idleTimeoutSecs field via the same path timeout uses. (Unit-suffixed name is deliberate per repo convention, even though it's inconsistent with the grandfathered timeout.)
• 0/omitted = unlimited. Explicit --idle-timeout 0 must override a config entry's positive value (merge with !== undefined, not truthiness, in resolveTarget), then normalize 0 to absent.
• ⚠️ substituteEnvVars() (src/lib/config.ts) must copy the new field — it currently drops any field it doesn't know, which is also why config-entry mcpVersion doesn't work today: Config-entry mcpVersion is silently dropped by substituteEnvVars #335.

New session state idle

• New stored SessionStatus value 'idle' + display status (○ idle, dim, with hint ↳ wakes on next use, e.g.: mcpc @name tools-list). getBridgeStatus() must return it before the pid-alive check, or pid-less idle sessions render as crashed.
• consolidateSessions(): exclude idle from both crash-marking branches and from restart eligibility (never background-restarted); keep it out of the cleanExpired removal so idle sessions survive consolidation.

Bridge idle monitor

• New small IdleMonitor class (src/bridge/idle-monitor.ts, testable with fake timers): single re-armed unref'd timeout; beginOperation()/endOperation() maintain an in-flight counter and reset the last-activity timestamp on completion (guarantees a fresh full period after the last op, per the acceptance matrix); an isDeferred() callback treats deferral as continuous activity.
• Activity hook: beginOperation() at the top of the bridge's handleMcpRequest (every user-issued IPC request, including explicit ping and the health checks that lead every CLI command), endOperation() in its finally. Proxy MCP handlers get the same wrapping — at the MCP-handler level, not HTTP level, so the long-lived GET notification stream and /health don't count. Nothing else touches the monitor: the internal 30s keepalive is a direct client.ping() (not IPC), and notification handlers / cache refreshes / resource re-syncs never call it. lastSeenAt is untouched by all this — it stays the keepalive clock and can't serve as the idle clock.
• isDeferred() = pending activeTasks ∨ active resourceSubscriptions ∨ open proxy client sessions. Combining --proxy + --idle-timeout prints a connect-time warning (proxy clients can't wake an idle bridge; only mcpc commands can).
• The timer keeps running while the connection is disconnected/reconnecting — an unreachable server is exactly when an idle bridge is pure waste.

Idle shutdown & wake

• On fire: new markSessionIdle() helper in src/lib/sessions.ts (one file-locked write: set status: 'idle', delete pid and mcpSessionId) → persist the tools + instructions snapshot for grep (below) → existing shutdown() path, which already gives us the HTTP DELETE for stateful sessions and the bounded SIGTERM→SIGKILL stdio child teardown.
• Race guard: handlePossibleExpiration() gets an isShuttingDown early-return so a keepalive failure racing the idle shutdown can't overwrite idle with expired.
• Expired→idle mapping: both places the bridge writes expired (runtime expiry, connect-time resumption rejection) write idle instead when idleTimeoutSecs is set. On top of Add --auto-restart option for automatic session recovery #312, extend ensureBridgeReady's fresh-retry predicate from session.autoRestart to session.autoRestart || session.server.idleTimeoutSecs so an idle-enabled session that lands in expired via the CLI-side classifier never dead-ends at "run restart"; the background restart in consolidateSessions stays gated on autoRestart only.
• Wake needs almost no code: idle bypasses the expired/unauthorized throws in ensureBridgeReady, the pid is gone, and mcpSessionId was cleared, so the normal restart branch connects fresh.

grep snapshot

• At idle shutdown the bridge writes its in-memory tools cache + server instructions to a per-session snapshot (e.g. ~/.mcpc/cache/<session>.tools.json, mode 0600, with cachedAt). Global mcpc grep reads the snapshot for idle sessions and badges the results; the snapshot is deleted on close/clean. v1 limitation: resources/prompts (grep's optional flags) aren't snapshotted.

Tests

• Unit: IdleMonitor with fake timers (fires; activity resets; in-flight past deadline defers then fresh period; deferral; stop); consolidateSessions idle exclusions; markSessionIdle atomicity; snapshot write/read; config-entry passthrough.
• E2E: new sessions/idle-timeout suite run under both --server-protocol legacy and modern: idles out (status idle, old bridge PID dead, mcpSessionId absent), wake gets a different session id (legacy-only assert), activity before the deadline resets it, an in-flight slow tool call survives past the deadline, --idle-timeout 0 never idles, global grep doesn't wake it but finds snapshot tools, resource subscription defers, restart preserves the setting, stdio variant asserts the server child process is gone.

Docs to touch per repo conventions: connect --help (+ an addHelpText block on activity semantics and --auto-restart precedence), CLAUDE.md session states, skills/mcpc/SKILL.md, CHANGELOG.

---

Generated by Claude Code