Capture stdio server stderr for debugging connection failures#198
Merged
Conversation
Stdio MCP servers inherit only a minimal whitelist of env vars from the MCP SDK (PATH, HOME, SHELL, ...). Vars like NODE_EXTRA_CA_CERTS, HTTPS_PROXY, and SSL_CERT_FILE must be forwarded explicitly via the config "env" block. Without this, stdio servers in TLS-intercepting proxy environments fail to reach their upstream APIs and mcpc connect appears to hang silently (stderr is suppressed unless --verbose). Documented in both `mcpc connect --help` and the README stdio config section, including a pointer to --verbose for diagnosing silent hangs. Refs #195
…ures Previously, stderr from a stdio MCP server was either inherited (verbose mode, but never visible since the bridge is spawned with stdio: 'ignore') or dropped entirely. That made failures like the one in #195 — a child server crashing because NODE_EXTRA_CA_CERTS wasn't forwarded — look like a silent hang on the CLI. Now the bridge always pipes the child's stderr, writes each line to ~/.mcpc/logs/bridge-<session>.log with a [server stderr] prefix, and keeps a bounded tail (50 lines / 8KB). On connect failure it appends the tail to the error message so the CLI shows the root cause. Refs #195
…tion - Replace hand-rolled line-buffering in createStdioTransport with readline.createInterface, which already handles \r\n / partial lines. - Trim "Stdio environment" block in `mcpc help connect` to 3 lines. - Cap each stderr line to STDERR_TAIL_MAX_CHARS on push and skip eviction when only one line remains, so a single oversized line (e.g. a long stack trace) can't squeeze itself out of the tail.
…help Both sections covered stdio-specific concerns; combine them into a single "Stdio servers" block.
…95-S4JLM # Conflicts: # CHANGELOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes stdio MCP server failures debuggable instead of silent (fixes #195).
Previously, stderr from a stdio server was either inherited (only in
--verbose, and even then dropped to/dev/nullsince the bridge is spawned withstdio: 'ignore') or discarded. A child crashing becauseNODE_EXTRA_CA_CERTSwasn't forwarded — the scenario in #195 — looked like a silent hang.Changes
src/core/transports.ts,src/core/factory.ts):createStdioTransportaccepts anonStderrLine(line)callback. When set, stderr is piped and split withreadline.createInterface(handles\r\n/ partial lines). Plumbed throughCreateTransportOptionsandCreateMcpClientOptions.src/bridge/index.ts): every line is logged to~/.mcpc/logs/bridge-<session>.logwith a[server stderr]prefix and kept in a bounded tail (50 lines / 8 KB, lines trimmed to 8 KB on push so a single giant stack trace doesn't evict itself). On connect failure, the tail is appended to the error message sent back to the CLI.src/cli/index.ts,README.md,CHANGELOG.md):mcpc connect --helpand the README now document the SDK's env whitelist and where stderr is captured. Earlier--verbosepointer was removed (it didn't actually work for stdio via the bridge).User-visible behavior
Test plan
npm run lintnpm run buildnpm run test:unit(532/532)…indicator instead of being evictedhttps://claude.ai/code/session_01PsfRHoKCVFnmxGqQfGEB1o