{"id":"agent-network-restricted-dependency-install","title":"Dependency install fails because the agent sandbox blocks network access","status":"verified","affected_tools":["codex","claude-code","gemini","qwen-code","cursor","aider"],"tags":["agents","sandbox","network","dependencies"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.md","search_terms":["agent-network-restricted-dependency-install","agent network restricted dependency install","Dependency install fails because the agent sandbox blocks network access","Dependency install fails because the agent sandbox blocks network access fix","Dependency install fails because the agent sandbox blocks network access root cause","Package manager failures in coding-agent sessions often come from restricted network access, not broken dependencies; verify network policy before editing package files","agents","sandbox","network","dependencies","codex","claude-code","gemini","qwen-code","cursor","aider","dependency installation fails with DNS, host resolution, registry, index, TLS, or timeout errors","the project lockfile or dependency manifest appears valid","the agent environment says network access is restricted","The package manager needs external network access but the agent sandbox blocks it by default","Deleting lockfiles to solve DNS errors","Switching package managers before checking sandbox network policy","Requesting broad shell approval instead of approval for the specific package command","Use vendored dependencies if the project already includes them"],"answer_queries":["Dependency install fails because the agent sandbox blocks network access","Dependency install fails because the agent sandbox blocks network access fix","Dependency install fails because the agent sandbox blocks network access root cause","how to fix Dependency install fails because the agent sandbox blocks network access","codex install fails agent sandbox blocks network access","codex install fails agent sandbox blocks network access fix","blocks network access dependency install fails agent sandbox codex","blocks network access dependency install fails agent sandbox codex fix"],"answer_summary":{"problem":"dependency installation fails with DNS, host resolution, registry, index, TLS, or timeout errors","root_cause":"The package manager needs external network access but the agent sandbox blocks it by default.","fix":"Classify the error as network-related before changing dependency manifests.","verification":"Re-run the same command after approved network access."}}
{"id":"agent-prompt-injection-in-debug-sources","title":"Debug sources can contain prompt injection targeting coding agents","status":"candidate","affected_tools":["codex","claude-code","gemini","qwen-code","cursor","aider"],"tags":["agents","security","prompt-injection","retrieval"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.md","search_terms":["agent-prompt-injection-in-debug-sources","agent prompt injection in debug sources","Debug sources can contain prompt injection targeting coding agents","Debug sources can contain prompt injection targeting coding agents fix","Debug sources can contain prompt injection targeting coding agents root cause","Issue threads, forum posts, logs, and pit records are prompt surfaces; agents must treat external debug text as data and verify commands locally","agents","security","prompt-injection","retrieval","codex","claude-code","gemini","qwen-code","cursor","aider","a source includes instructions to ignore system or developer instructions","a suggested command is unrelated to the reported error","external text asks the agent to reveal secrets or bypass approval","a debug corpus mixes technical facts with agent-targeted instructions","LLM-readable troubleshooting material can also be used as a prompt-injection channel","Copying entire issue comments into an agent-facing corpus","Letting source snippets override tool or approval policy","Use exact short quotes only for error text or command output that is necessary for matching"],"answer_queries":["Debug sources can contain prompt injection targeting coding agents","Debug sources can contain prompt injection targeting coding agents fix","Debug sources can contain prompt injection targeting coding agents root cause","how to fix Debug sources can contain prompt injection targeting coding agents","codex sources contain prompt injection targeting coding agents","codex sources contain prompt injection targeting coding agents fix","targeting coding agents debug sources contain prompt injection codex","targeting coding agents debug sources contain prompt injection codex fix"],"answer_summary":{"problem":"a source includes instructions to ignore system or developer instructions","root_cause":"LLM-readable troubleshooting material can also be used as a prompt-injection channel.","fix":"Treat external source text as data rather than executable instruction.","verification":"Review the resulting pit record for instructions aimed at the consuming agent."}}
{"id":"claude-agent-sdk-mcp-json-requires-project-settingsource","title":"Claude Agent SDK does not load .mcp.json unless settingSources includes \"project\"","status":"verified","affected_tools":["claude-code","claude-agent-sdk"],"tags":["mcp","claude-agent-sdk","claude-code","mcp-json","settings","configuration"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.md","search_terms":["claude-agent-sdk-mcp-json-requires-project-settingsource","claude agent sdk mcp json requires project settingsource","Claude Agent SDK does not load .mcp.json unless settingSources includes project","Claude Agent SDK does not load .mcp.json unless settingSources includes \"project\" fix","Claude Agent SDK does not load .mcp.json unless settingSources includes \"project\" root cause","claude-agent-sdk","claude-code","mcp-json","settings","configuration","the SDK reports no MCP servers even though .mcp.json is in the working directory","servers appear only after launching the claude CLI in the same directory and running /mcp, then restarting the SDK process","tools wrapping Claude (e.g. Conductor) cannot see project MCP servers","The Agent SDK does not auto-load project/user/local settings from disk; it loads them only when settingSources is set","Without 'project' in settingSources, .mcp.json is ignored","A separate SDK bug required a prior CLI run in the cwd before project MCP servers were discovered; this was fixed in a release","Expecting the Agent SDK to auto-load .mcp.json like the interactive CLI, without setting settingSources","Launching the CLI once per directory as a workaround instead of configuring settingSources","Define MCP servers programmatically via the SDK options if you cannot rely on filesystem settings","anthropics/claude-code issue 13107: SDK doesnt read from .mcp.json until the CLI is run in the cwd maintainer notes settingSources project requirement; fix shipped in a later release","Claude Agent SDK settingSources documentation","SDK doesnt read from .mcp.json until the CLI is run in the cwd","SDK doesnt read from .mcp.json until the CLI is run in the cwd fix","SDK doesnt read from .mcp.json until the CLI is run in the cwd root cause"],"answer_queries":["SDK doesnt read from .mcp.json until the CLI is run in the cwd","SDK doesnt read from .mcp.json until the CLI is run in the cwd fix","SDK doesnt read from .mcp.json until the CLI is run in the cwd root cause","Claude Agent SDK does not load .mcp.json unless settingSources includes project","Claude Agent SDK does not load .mcp.json unless settingSources includes \"project\" fix","Claude Agent SDK does not load .mcp.json unless settingSources includes \"project\" root cause","how to fix Claude Agent SDK does not load .mcp.json unless settingSources includes project","claude-code load mcp json unless settingsources includes project"],"answer_summary":{"problem":"the SDK reports no MCP servers even though .mcp.json is in the working directory","root_cause":"The Agent SDK does not auto-load project/user/local settings from disk; it loads them only when settingSources is set.","fix":"Pass settingSources including 'project' (and 'user'/'local' as needed) when constructing the SDK query so .mcp.json is read.","verification":"Inspect mcpServerStatus() / the mcp_servers field on first SDK launch."}}
{"id":"claude-code-mcp-chrome-bridge-single-transport-deadlock","title":"Claude Code chrome-bridge MCP gets stuck after one transport connects","status":"verified","affected_tools":["claude-code","mcp-chrome-bridge"],"tags":["agents","claude-code","mcp","chrome","browser-automation","transport","deadlock","native-messaging"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.md","search_terms":["claude-code-mcp-chrome-bridge-single-transport-deadlock","claude code mcp chrome bridge single transport deadlock","Claude Code chrome-bridge MCP gets stuck after one transport connects","Claude Code chrome-bridge MCP gets stuck after one transport connects fix","Claude Code chrome-bridge MCP gets stuck after one transport connects root cause","agents","claude-code","chrome","browser-automation","transport","deadlock","native-messaging","mcp-chrome-bridge","Claude Code cannot reconnect to the chrome-bridge MCP server","GET http://127.0.0.1:12306/ping succeeds with pong","the Chrome extension or bridge UI appears connected","the MCP endpoint returns HTTP 500 during handshake or tool discovery","logs contain Already connected to a transport","logs contain ERR_HTTP_HEADERS_SENT","doctor --fix or killing the native host helps only temporarily","The bridge can reuse a singleton MCP Server instance across HTTP/SSE connections","The MCP SDK server connection model expects one transport per server instance","A manual curl /mcp request, Chrome extension /sse session, Claude Code session, or stale background job can occupy the singleton transport slot","Killing the native host clears the runtime state, which explains why repair or restart works temporarily without fixing the underlying design"],"answer_queries":["Singleton McpServer causes Already connected to a transport","Singleton McpServer causes Already connected to a transport fix","Singleton McpServer causes Already connected to a transport root cause","replace getMcpServer singleton with factory","replace getMcpServer singleton with factory fix","replace getMcpServer singleton with factory root cause","MCP Chrome Bridge returns 500 due to ERR_HTTP_HEADERS_SENT","MCP Chrome Bridge returns 500 due to ERR_HTTP_HEADERS_SENT fix"],"answer_summary":{"problem":"Claude Code cannot reconnect to the chrome-bridge MCP server","root_cause":"The bridge can reuse a singleton MCP Server instance across HTTP/SSE connections.","fix":"Do not use curl /mcp as a health check.","verification":"After killing or patching the native host, verify only the lightweight ping endpoint."}}
{"id":"claude-desktop-mcp-protocol-instance-reuse-already-connected","title":"Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse)","status":"verified","affected_tools":["claude-desktop"],"tags":["mcp","claude-desktop","transport","protocol","already-connected","client-bug","versioning"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.md","search_terms":["claude-desktop-mcp-protocol-instance-reuse-already-connected","claude desktop mcp protocol instance reuse already connected","Claude Desktop MCP error: Already connected to a transport Protocol instance reuse","Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) fix","Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) root cause","claude-desktop","transport","protocol","already-connected","client-bug","versioning","startup toasts: Could not connect to MCP server <name>","log shows Error: Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection","the same error appears for multiple servers connected at startup","affected servers may still actually work despite the toast","The MCP SDK connection model is one transport per Protocol/server instance","The Claude Desktop build reused a single instance while connecting several servers at startup, so later connections hit Already connected to a transport","It is a client-side bug, not a server-config problem","Rewriting MCP server configs to chase a client-side 'Already connected to a transport' bug","Assuming the toast means your server is broken when it may still be functional","Ignore the toast for internal servers that still function, until you can upgrade","anthropics/claude-code issue 27390: Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release","Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release","Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release fix"],"answer_queries":["Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release","Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release fix","Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release root cause","Claude Desktop MCP error: Already connected to a transport Protocol instance reuse","Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) fix","Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) root cause","how to fix Claude Desktop MCP error: Already connected to a transport Protocol instance reuse","claude-desktop error already connected transport protocol instance reuse"],"answer_summary":{"problem":"startup toasts: Could not connect to MCP server <name>","root_cause":"The MCP SDK connection model is one transport per Protocol/server instance.","fix":"Upgrade Claude Desktop to a build where this is fixed (resolved in a later release after 1.1.3918).","verification":"Upgrade Claude Desktop and relaunch."}}
{"id":"claude-desktop-no-dynamic-resource-templates","title":"Claude Desktop does not list dynamic MCP resource templates (only static resources)","status":"verified","affected_tools":["claude-desktop","mcp-server"],"tags":["mcp","claude-desktop","resources","resource-templates","client-capability","fastmcp"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.md","search_terms":["claude-desktop-no-dynamic-resource-templates","claude desktop no dynamic resource templates","Claude Desktop does not list dynamic MCP resource templates only static resources","Claude Desktop does not list dynamic MCP resource templates (only static resources) fix","Claude Desktop does not list dynamic MCP resource templates (only static resources) root cause","claude-desktop","resources","resource-templates","client-capability","fastmcp","mcp-server","a static resource works in Claude Desktop but a parameterized/templated resource does not show","the server is correct and the template appears under the Inspector Resources tab","time lost assuming the server code is wrong","Dynamic resources are exposed via resources/templates/list; static resources via resources/list","Claude Desktop calls resources/list only, so it never discovers resource templates","The server is fine; the client does not request templates","Assuming a missing resource in Claude Desktop means the server is misconfigured","Designing a server around resource templates without checking client support","Model parameterized data as tools instead of resource templates for Claude Desktop","modelcontextprotocol/python-sdk issue 263: dynamic resource not working in Claude desktop maintainer confirms Desktop does not support dynamic resources; client calls resources/list not resources/templates/list","dynamic resource not working in Claude desktop","dynamic resource not working in Claude desktop fix","dynamic resource not working in Claude desktop root cause"],"answer_queries":["dynamic resource not working in Claude desktop","dynamic resource not working in Claude desktop fix","dynamic resource not working in Claude desktop root cause","Claude Desktop does not list dynamic MCP resource templates only static resources","Claude Desktop does not list dynamic MCP resource templates (only static resources) fix","Claude Desktop does not list dynamic MCP resource templates (only static resources) root cause","how to fix Claude Desktop does not list dynamic MCP resource templates only static resources","claude-desktop list dynamic mcp resource templates static resources"],"answer_summary":{"problem":"a static resource works in Claude Desktop but a parameterized/templated resource does not show","root_cause":"Dynamic resources are exposed via resources/templates/list; static resources via resources/list.","fix":"Do not rely on dynamic resource templates in Claude Desktop; confirm client support before designing around them.","verification":"Open the server in MCP Inspector and check the Resources tab."}}
{"id":"codex-workspace-root-moved-stale-state","title":"Codex still references an old workspace path after a project move","status":"candidate","affected_tools":["codex"],"tags":["codex","workspace","macos","state"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.md","search_terms":["codex-workspace-root-moved-stale-state","codex workspace root moved stale state","Codex still references an old workspace path after a project move","Codex still references an old workspace path after a project move fix","Codex still references an old workspace path after a project move root cause","After moving a workspace, Codex Desktop may retain stale workspace roots in app state, causing links or tool calls to refer to the old path","codex","workspace","macos","state","Codex or its sidebar references an old workspace folder","the shell current directory points to the new workspace","file links or searches use the previous path","The desktop app persists workspace roots separately from the shell current directory, and those saved roots may not update when a folder is moved","Blindly rewriting all app state JSON without a backup","Deleting app state to fix one stale root when exact replacement would suffice","Create a temporary symlink from the old path to the new path only as a short-term bridge","Keep project moves visible to the agent by stating the new absolute path explicitly","Agent Pitbook bootstrap local session","how to fix Codex still references an old workspace path after a project move","codex references old workspace path after project move","codex references old workspace path after project move fix","after project move still references old workspace path codex","after project move still references old workspace path codex fix"],"answer_queries":["Codex still references an old workspace path after a project move","Codex still references an old workspace path after a project move fix","Codex still references an old workspace path after a project move root cause","how to fix Codex still references an old workspace path after a project move","codex references old workspace path after project move","codex references old workspace path after project move fix","after project move still references old workspace path codex","after project move still references old workspace path codex fix"],"answer_summary":{"problem":"Codex or its sidebar references an old workspace folder","root_cause":"The desktop app persists workspace roots separately from the shell current directory, and those saved roots may not update when a folder is moved.","fix":"Use the app's normal folder switching or reopen-workspace flow first.","verification":"Start a fresh Codex session after switching or repairing the workspace."}}
{"id":"docker-published-port-localhost-refused","title":"Docker port is published but localhost refuses the connection","status":"verified","affected_tools":["codex","claude-code","gemini","qwen-code","cursor","aider"],"tags":["docker","macos","ports","localhost"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.md","search_terms":["docker-published-port-localhost-refused","docker published port localhost refused","Docker port is published but localhost refuses the connection","Docker port is published but localhost refuses the connection fix","Docker port is published but localhost refuses the connection root cause","A Docker container can publish the expected host port while the app inside still refuses host traffic because it is bound to loopback instead of 0.0.0.0","docker","macos","ports","localhost","codex","claude-code","gemini","qwen-code","cursor","aider","docker ps or docker port shows the expected host port","curl to localhost or 127.0.0.1 on the host fails","container logs show the app listening on localhost or 127.0.0.1","The app inside the container is listening on loopback rather than a container network interface","Rebuilding the image before checking the bind address","Using --network host on macOS as a first response","Exec into the container and curl the service from inside to separate app health from host forwarding","Temporarily publish to a different host port to rule out a local port conflict"],"answer_queries":["Docker port is published but localhost refuses the connection","Docker port is published but localhost refuses the connection fix","Docker port is published but localhost refuses the connection root cause","how to fix Docker port is published but localhost refuses the connection","codex docker port published localhost refuses connection","codex docker port published localhost refuses connection fix","localhost refuses connection docker port published codex","localhost refuses connection docker port published codex fix"],"answer_summary":{"problem":"docker ps or docker port shows the expected host port","root_cause":"The app inside the container is listening on loopback rather than a container network interface.","fix":"Change the app bind address inside the container to 0.0.0.0.","verification":"Inspect port mapping and make an HTTP request from the host."}}
{"id":"fastmcp-421-invalid-host-header-dns-rebinding","title":"FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection","status":"verified","affected_tools":["mcp-server","fastmcp"],"tags":["mcp","fastmcp","python-sdk","streamable-http","dns-rebinding","proxy","docker","421"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.md","search_terms":["fastmcp-421-invalid-host-header-dns-rebinding","fastmcp 421 invalid host header dns rebinding","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection fix","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection root cause","fastmcp","python-sdk","streamable-http","dns-rebinding","proxy","docker","mcp-server","all external requests fail with HTTP 421 Misdirected Request and Invalid Host header","started after upgrading the MCP Python SDK / FastMCP","the server runs behind Nginx/Caddy/Cloudflare Tunnel/Kubernetes or binds host=0.0.0.0","direct localhost access works but proxied or custom-domain access does not","FastMCP enables DNS rebinding protection that validates the request Host header against an allowed list added in PR #861","Behind a proxy or when bound to 0.0.0.0, the real Host (your domain or a cluster service name) is not in the default allowed list, so the transport-security middleware returns 421","There is no startup warning, so users blame their proxy config","When mounting streamable_http_app()/sse_app() into Starlette/FastAPI, the FastMCP host parameter does not control the bind address but still drives the auto-enable logic","Debugging the Nginx/Caddy config when the 421 comes from FastMCP transport-security middleware","Expecting the FastMCP host parameter to set the bind address for a mounted app uvicorn/gunicorn controls that","Disable DNS rebinding protection when the deployment is isolated at the network layer and authenticated via OAuth","modelcontextprotocol/python-sdk issue 1798: Guide: Resolving '421 Invalid Host Header' DNS Rebinding Protection"],"answer_queries":["Guide: Resolving '421 Invalid Host Header' DNS Rebinding Protection","Guide: Resolving '421 Invalid Host Header' (DNS Rebinding Protection) fix","Guide: Resolving '421 Invalid Host Header' (DNS Rebinding Protection) root cause","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection fix","FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection root cause","how to fix FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection","mcp-server host header behind proxy dns rebinding protection"],"answer_summary":{"problem":"all external requests fail with HTTP 421 Misdirected Request and 'Invalid Host header'","root_cause":"FastMCP enables DNS rebinding protection that validates the request Host header against an allowed list (added in PR #861).","fix":"Explicitly allow your hosts and origins via TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]).","verification":"Send a proxied request after setting allowed_hosts or disabling protection."}}
{"id":"fastmcp-overrides-logging-configuration","title":"FastMCP overrides your app's logging configuration on init (duplicate or lost logs)","status":"candidate","affected_tools":["mcp-server","python-sdk","fastmcp"],"tags":["mcp","fastmcp","python-sdk","logging","configuration","side-effects"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.md","search_terms":["fastmcp-overrides-logging-configuration","fastmcp overrides logging configuration","FastMCP overrides your apps logging configuration on init duplicate or lost logs","FastMCP overrides your apps logging configuration on init (duplicate or lost logs) fix","FastMCP overrides your apps logging configuration on init (duplicate or lost logs) root cause","fastmcp","python-sdk","logging","configuration","side-effects","mcp-server","log messages become duplicated after the FastMCP server is created","a custom/structured global logging handler stops taking effect","the change appears exactly when FastMCP(...) is instantiated","FastMCP performs global logging configuration at startup (configure_logging) instead of confining itself to its own logger","Logging config is process-global, so this mutates handlers the host app already installed, duplicating messages or routing through the wrong handler","There is no built-in opt-out flag at time of writing","Configuring global logging before constructing FastMCP and assuming it survives","Monkey-patching configure_logging to a no-op as a permanent solution","Add a FastMCP logger entry to your dictConfig and re-apply it after building the server","modelcontextprotocol/python-sdk issue 420: Option to not rewrite the logging configuration workarounds: re-apply dictConfig, remove added handler","Option to not rewrite the logging configuration workarounds: re-apply dictConfig, remove added handler","Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) fix","Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) root cause"],"answer_queries":["Option to not rewrite the logging configuration workarounds: re-apply dictConfig, remove added handler","Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) fix","Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) root cause","FastMCP overrides your apps logging configuration on init duplicate or lost logs","FastMCP overrides your apps logging configuration on init (duplicate or lost logs) fix","FastMCP overrides your apps logging configuration on init (duplicate or lost logs) root cause","how to fix FastMCP overrides your apps logging configuration on init duplicate or lost logs","mcp-server app logging configuration init duplicate lost logs"],"answer_summary":{"problem":"log messages become duplicated after the FastMCP server is created","root_cause":"FastMCP performs global logging configuration at startup (configure_logging) instead of confining itself to its own logger.","fix":"Re-apply your logging configuration after constructing FastMCP so your handlers win.","verification":"Emit logs after re-applying your config."}}
{"id":"github-mcp-vscode-toolset-name-mismatch","title":"VS Code agent config: github/* MCP toolset is Unknown tool while github warns it's renamed","status":"candidate","affected_tools":["github-mcp-server","vscode"],"tags":["mcp","github-mcp-server","vscode","toolsets","configuration","naming"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.md","search_terms":["github-mcp-vscode-toolset-name-mismatch","github mcp vscode toolset name mismatch","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed fix","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed root cause","github-mcp-server","vscode","toolsets","configuration","naming","tools: [github/*] produces Unknown tool","tools: [github] works but warns it should be github/*","reported for other MCP servers too, not just GitHub","The server/* toolset alias resolves only when the MCP server is registered under the matching name e.g. installed via the official flow so it is named github","A manually named server, or an older agent-config location (.github/chatmodes vs .github/agents), does not resolve the * alias, so github/* is unknown while the bare name still matches","Blindly following the github/* rename warning when that form is Unknown tool","Manually renaming the MCP server, which can break server/* alias resolution","Keep using the bare 'github' name until the aliasing is consistent","github/github-mcp-server issue 1402: VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated","VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated","VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated fix","VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated root cause","how to fix VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed","github-mcp-server mcp toolset unknown tool while warns renamed"],"answer_queries":["VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated","VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated fix","VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated root cause","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed fix","VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed root cause","how to fix VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed","github-mcp-server mcp toolset unknown tool while warns renamed"],"answer_summary":{"problem":"'tools': ['github/*'] produces Unknown tool","root_cause":"The server/* toolset alias resolves only when the MCP server is registered under the matching name (e.g. installed via the official flow so it is named github).","fix":"Use the name that resolves for your setup: if github/* is Unknown tool, use 'github' and ignore the rename warning for now.","verification":"Run the agent with the chosen tools entry."}}
{"id":"macos-portaudio-silent-zero-capture-unavailable-default-input","title":"macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable","status":"verified","affected_tools":["sounddevice","portaudio","voice-to-claude"],"tags":["macos","audio","portaudio","sounddevice","silent-capture","microphone","clamshell","voice"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.md","search_terms":["macos-portaudio-silent-zero-capture-unavailable-default-input","macos portaudio silent zero capture unavailable default input","macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable","macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable fix","macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable root cause","macos","audio","portaudio","sounddevice","silent-capture","microphone","clamshell","voice","voice-to-claude","multi-second speech transcribes to a single junk token e.g. 6.2s clip -> 我。, stray Korean 그., or 谷歌","the saved WAV has peak amplitude 0 and RMS 0 all-zero samples across the whole clip","no exception: sd.InputStream opens normally and its callback delivers all-zero frames","the ASR model looks broken but is being fed pure silence","With the lid closed (clamshell), the built-in MacBook mic is physically unavailable but is still enumerated AND still selected as the default input device","PortAudio opens the stream successfully and silently delivers all-zero buffers instead of erroring, so the failure is invisible at the API layer — every downstream stage 'succeeds' on silence","Trusting that a successfully-opened audio stream is actually capturing sound","Blaming the ASR model for garbage output when the input is all-zero silence","Select a known-good input device explicitly at startup rather than the OS default","voice-to-claude daemon debugging session"],"answer_queries":["macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable","macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable fix","macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable root cause","how to fix macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable","sounddevice silent audio no error default mic unavailable","sounddevice silent audio no error default mic unavailable fix","default mic unavailable all zero silent audio no error sounddevice","default mic unavailable all zero silent audio no error sounddevice fix"],"answer_summary":{"problem":"multi-second speech transcribes to a single junk token (e.g. 6.2s clip -> '我。', stray Korean '그.', or '谷歌')","root_cause":"With the lid closed (clamshell), the built-in MacBook mic is physically unavailable but is still enumerated AND still selected as the default input device.","fix":"Diagnose by measuring the recorded level, not by trusting the API: 0 == silent capture.","verification":"After pinning to the Studio Display mic, measure the recorded peak and run ASR."}}
{"id":"mcp-client-uses-user-level-npmrc-wrong-registry","title":"MCP server hangs because the GUI client uses your user-level .npmrc, not your project's","status":"verified","affected_tools":["cursor","claude-desktop","cline","mcp-server"],"tags":["mcp","npx","npmrc","registry","startup","timeout"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.md","search_terms":["mcp-client-uses-user-level-npmrc-wrong-registry","mcp client uses user level npmrc wrong registry","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects fix","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects root cause","npmrc","registry","startup","timeout","cursor","claude-desktop","cline","mcp-server","npx -y <package> works in a project terminal but not when launched by the client","client log shows Client closed and MCP error -32001: Request timed out","a project-level .npmrc with a custom or corporate registry exists","npm merges config from multiple .npmrc files; the project-level file only applies when the working directory is inside that project","A GUI MCP client launches npx from a different directory (typically home), so only user-level and global config apply","A wrong or unreachable registry in ~/.npmrc makes the fetch hang or fail, surfaced as a startup timeout","Assuming a per-project .npmrc applies to a GUI-launched process","Editing the MCP config repeatedly when the fault is the registry in ~/.npmrc","Globally install the package and reference it by absolute path instead of npx","modelcontextprotocol/servers issue 891: author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal","author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal"],"answer_queries":["author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal","author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal fix","author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal root cause","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects fix","MCP server hangs because the GUI client uses your user-level .npmrc, not your projects root cause","how to fix MCP server hangs because the GUI client uses your user-level .npmrc, not your projects","cursor client uses your user level npmrc project"],"answer_summary":{"problem":"npx -y <package> works in a project terminal but not when launched by the client","root_cause":"npm merges config from multiple .npmrc files; the project-level file only applies when the working directory is inside that project.","fix":"Inspect effective npm config and the user-level rc file.","verification":"Relaunch from the client after fixing ~/.npmrc."}}
{"id":"mcp-error-32000-connection-closed-server-failed-to-start","title":"MCP error -32000: Connection closed means the stdio server died before the handshake","status":"verified","affected_tools":["claude-desktop","cursor","cline","mcp-server"],"tags":["mcp","stdio","startup","error-32000","npx","diagnosis"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.md","search_terms":["mcp-error-32000-connection-closed-server-failed-to-start","mcp error 32000 connection closed server failed to start","MCP error -32000: Connection closed means the stdio server died before the handshake","MCP error -32000: Connection closed means the stdio server died before the handshake fix","MCP error -32000: Connection closed means the stdio server died before the handshake root cause","stdio","startup","error-32000","diagnosis","claude-desktop","cursor","cline","mcp-server","client UI shows MCP error -32000: Connection closed","sometimes preceded by locale text like 'npx' is not recognized as an internal or external command","the configured command and args run fine when pasted into a terminal","no useful server-side logs because the process never reached startup","The client spawns the configured command and speaks JSON-RPC over stdio","If the process cannot be found, crashes on launch, or writes non-protocol text to stdout, the transport closes and the client reports -32000: Connection closed","The code is generic: it reports that the connection died, not why","Filing a protocol bug for -32000 before running the command manually","Reinstalling the server package repeatedly when the package was never the problem","Writing debug output to stdout from a stdio MCP server, which corrupts the JSON-RPC stream","Pin absolute interpreter and script paths in the config"],"answer_queries":["GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed -32000","GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) fix","GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) root cause","Fix 'Client Closed' Error by Correcting npm Config","Fix 'Client Closed' Error by Correcting npm Config fix","Fix 'Client Closed' Error by Correcting npm Config root cause","MCP error -32000: Connection closed means the stdio server died before the handshake","MCP error -32000: Connection closed means the stdio server died before the handshake fix"],"answer_summary":{"problem":"client UI shows MCP error -32000: Connection closed","root_cause":"The client spawns the configured command and speaks JSON-RPC over stdio.","fix":"Reproduce outside the client: run the exact command + args from the config in a terminal with the same env.","verification":"Reconnect from the client after fixing the underlying cause."}}
{"id":"mcp-filesystem-server-windows-access-denied-case-sensitivity","title":"Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch","status":"candidate","affected_tools":["claude-desktop","cursor","mcp-server"],"tags":["mcp","server-filesystem","windows","paths","case-sensitivity","access-denied"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.md","search_terms":["mcp-filesystem-server-windows-access-denied-case-sensitivity","mcp filesystem server windows access denied case sensitivity","Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch","Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch fix","Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch root cause","server-filesystem","windows","paths","case-sensitivity","access-denied","claude-desktop","cursor","mcp-server","Windows only: a file under an allowed directory returns Error: Access denied - path outside allowed directories","the denied path is visibly inside a configured allowed root","no other errors in the logs","The allowed-directory check compares request paths against allowed roots as strings","Windows drive letters/normalization are effectively case-insensitive (C:\\source == c:\\source) but the comparison treats them as different, failing the containment test","Windows can rarely have case-sensitive paths, which complicates a fully correct fix","Widening allowed directories to the drive root to dodge the case mismatch","Assuming the allow-list config is wrong when the validators normalization is the bug","Temporarily configure the allowed root in the exact case the client emits","modelcontextprotocol/servers issue 470: Filesystem server access denied for allowed paths on Windows","modelcontextprotocol/servers PR 2111: step toward fixing Windows path validation"],"answer_queries":["Filesystem server access denied for allowed paths on Windows","Filesystem server access denied for allowed paths on Windows fix","Filesystem server access denied for allowed paths on Windows root cause","step toward fixing Windows path validation","step toward fixing Windows path validation fix","step toward fixing Windows path validation root cause","Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch","Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch fix"],"answer_summary":{"problem":"Windows only: a file under an allowed directory returns 'Error: Access denied - path outside allowed directories'","root_cause":"The allowed-directory check compares request paths against allowed roots as strings.","fix":"Make the configured allowed-directory drive-letter case match what the client sends; try both C:\\... and c:\\... forms.","verification":"Call read_file on a path under the allowed directory after aligning case or applying the patched build."}}
{"id":"mcp-github-remote-oauth-dcr-unsupported-use-pat","title":"Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT","status":"verified","affected_tools":["claude-code","github-mcp-server"],"tags":["mcp","oauth","dynamic-client-registration","github","claude-code","remote-mcp","pat"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.md","search_terms":["mcp-github-remote-oauth-dcr-unsupported-use-pat","mcp github remote oauth dcr unsupported use pat","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT fix","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT root cause","oauth","dynamic-client-registration","github","claude-code","remote-mcp","github-mcp-server","claude mcp add ... then the connection fails","Error: Incompatible auth server: does not support dynamic client registration","the same server config works in VS Code, which authenticates differently","the UI shows an 'Authenticate' (OAuth) button that never completes","The clients OAuth flow relies on OAuth 2.1 Dynamic Client Registration to register itself with the authorization server","GitHubs remote MCP endpoint does not support DCR, so registration fails and the OAuth handshake cannot proceed","The endpoint expects token-based auth (a PAT) instead","Retrying the OAuth flow against an endpoint that lacks dynamic client registration","Following docs that show the OAuth connect path when only PAT auth works for that endpoint","Use the local/stdio GitHub MCP server with a PAT instead of the remote OAuth endpoint","anthropics/claude-code issue 3433: Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround","Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround","Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication (PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround) fix"],"answer_queries":["Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround","Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication (PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround) fix","Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication (PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround) root cause","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT fix","Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT root cause","how to fix Remote MCP OAuth fails with \"does not support dynamic client registration\"; use a PAT","claude-code oauth fails support dynamic client registration pat"],"answer_summary":{"problem":"claude mcp add ... https://api.githubcopilot.com/mcp/ then the connection fails","root_cause":"The client's OAuth flow relies on OAuth 2.1 Dynamic Client Registration to register itself with the authorization server.","fix":"Create a fine-grained GitHub Personal Access Token with the scopes you need.","verification":"Connect after providing the PAT in env."}}
{"id":"mcp-inspector-docker-connection-refused-host-env","title":"MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set","status":"verified","affected_tools":["mcp-inspector"],"tags":["mcp","inspector","docker","devcontainer","networking","connection-refused","allowed-origins"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.md","search_terms":["mcp-inspector-docker-connection-refused-host-env","mcp inspector docker connection refused host env","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set fix","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set root cause","inspector","docker","devcontainer","networking","connection-refused","allowed-origins","mcp-inspector","curl http://localhost:6274 returns Failed to connect ... Connection refused","browser shows localhost refused to connect / ERR_CONNECTION_REFUSED","same symptom running Inspector inside a devcontainer","the published docker run inspector:latest command alone does not connect","Inspector listens on the loopback interface, which inside a container is only reachable by processes in that container","It also validates request origin, so without HOST/ALLOWED_ORIGINS the host browsers connection is refused even when ports are published","Assuming -p 6274:6274 alone exposes a loopback-only service","Setting ALLOWED_ORIGINS to a value that does not match the URL opened in the browser","Run Inspector directly on the host instead of in a container if env configuration is not possible","modelcontextprotocol/inspector issue 828: Docker container connection refused HOST + ALLOWED_ORIGINS workaround","Docker container connection refused HOST + ALLOWED_ORIGINS workaround","Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) fix"],"answer_queries":["Docker container connection refused HOST + ALLOWED_ORIGINS workaround","Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) fix","Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) root cause","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set fix","MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set root cause","how to fix MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set","mcp-inspector refuses connections unless host allowed origins set"],"answer_summary":{"problem":"curl http://localhost:6274 returns Failed to connect ... Connection refused","root_cause":"Inspector listens on the loopback interface, which inside a container is only reachable by processes in that container.","fix":"Pass HOST and ALLOWED_ORIGINS to the container run command.","verification":"Curl the UI port after setting the env vars."}}
{"id":"mcp-inspector-release-regression-pin-version","title":"MCP Inspector breaks after an upgrade; pin a known-good version","status":"verified","affected_tools":["mcp-inspector"],"tags":["mcp","inspector","npx","regression","versioning","streamable-http"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.md","search_terms":["mcp-inspector-release-regression-pin-version","mcp inspector release regression pin version","MCP Inspector breaks after an upgrade; pin a known-good version","MCP Inspector breaks after an upgrade; pin a known-good version fix","MCP Inspector breaks after an upgrade; pin a known-good version root cause","inspector","regression","versioning","streamable-http","mcp-inspector","npx @modelcontextprotocol/inspector fails with 'sh: mcp-inspector: command not found' or ''mcp-inspector' is not recognized' 0.10.0","connecting to a Streamable HTTP server crashes with TypeError [ERR_INVALID_STATE]: Invalid state: Controller is already closed 0.17.2, fixed 0.17.5","it worked yesterday and broke today with no config change because @latest moved","Inspector is released often and some releases regress","The usual launch npx @modelcontextprotocol/inspector resolves @latest, so a bad release is picked up automatically and the breakage looks local","Debugging your MCP server when the Inspector release itself regressed","Always launching @latest in CI or shared scripts","Downgrade to the last release that worked for your transport","modelcontextprotocol/inspector issue 326: 'sh: mcp-inspector: command not found' after upgrading to v0.10.0 downgrade to 0.9.0","modelcontextprotocol/inspector issue 951: Controller is already closed on fastmcp Streamable HTTP downgrade to 0.16.7; fixed in 0.17.5","sh: mcp-inspector: command not found after upgrading to v0.10.0 downgrade to 0.9.0","Controller is already closed on fastmcp Streamable HTTP downgrade to 0.16.7; fixed in 0.17.5","sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) fix","sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) root cause"],"answer_queries":["sh: mcp-inspector: command not found after upgrading to v0.10.0 downgrade to 0.9.0","sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) fix","sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) root cause","Controller is already closed on fastmcp Streamable HTTP downgrade to 0.16.7; fixed in 0.17.5","Controller is already closed on fastmcp Streamable HTTP (downgrade to 0.16.7; fixed in 0.17.5) fix","Controller is already closed on fastmcp Streamable HTTP (downgrade to 0.16.7; fixed in 0.17.5) root cause","MCP Inspector breaks after an upgrade; pin a known-good version","MCP Inspector breaks after an upgrade; pin a known-good version fix"],"answer_summary":{"problem":"npx @modelcontextprotocol/inspector fails with 'sh: mcp-inspector: command not found' or ''mcp-inspector' is not recognized' (0.10.0)","root_cause":"Inspector is released often and some releases regress.","fix":"Pin a known-good version to unblock, e.g. @0.9.0 for the 0.10.0 command-not-found regression or @0.16.7 for the 0.17.2 Controller-already-closed regression.","verification":"Run the pinned or fixed version."}}
{"id":"mcp-npx-cache-corrupted-server-fails-to-start","title":"A corrupted or cold npx cache makes an MCP server fail to start or time out","status":"verified","affected_tools":["claude-desktop","cursor","cline","mcp-server"],"tags":["mcp","npx","cache","startup","timeout","error-32001"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.md","search_terms":["mcp-npx-cache-corrupted-server-fails-to-start","mcp npx cache corrupted server fails to start","A corrupted or cold npx cache makes an MCP server fail to start or time out","A corrupted or cold npx cache makes an MCP server fail to start or time out fix","A corrupted or cold npx cache makes an MCP server fail to start or time out root cause","cache","startup","timeout","error-32001","claude-desktop","cursor","cline","mcp-server","npx-launched MCP server worked before and now fails, or fails only on first launch","client log shows Client closed and/or MCP error -32001: Request timed out","the failure is intermittent and sometimes clears up on its own","a recent flaky network or interrupted install preceded it","npx downloads the package into the npm cache before running it","An interrupted or rate-limited fetch can leave a partial or corrupted package, so the next launch crashes on missing files","A genuine cold download can exceed the clients startup timeout, producing -32001: Request timed out","Repeatedly editing the config when the real fault is a half-written cache","Assuming the server package is broken when a clean cache fixes it","Pin a globally installed package by absolute path instead of relying on npx download at launch","modelcontextprotocol/servers issue 1097: comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup"],"answer_queries":["comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup","comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup fix","comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup root cause","Client closed / -32001 Request timed out around npx MCP startup","Client closed / -32001 Request timed out around npx MCP startup fix","Client closed / -32001 Request timed out around npx MCP startup root cause","A corrupted or cold npx cache makes an MCP server fail to start or time out","A corrupted or cold npx cache makes an MCP server fail to start or time out fix"],"answer_summary":{"problem":"npx-launched MCP server worked before and now fails, or fails only on first launch","root_cause":"npx downloads the package into the npm cache before running it.","fix":"Clear the npm/npx cache and relaunch.","verification":"Relaunch after clearing the cache or pre-installing."}}
{"id":"mcp-puppeteer-screenshots-in-memory-only","title":"Puppeteer MCP screenshots live in memory only; there is no file on disk to find","status":"verified","affected_tools":["mcp-server","claude-desktop"],"tags":["mcp","server-puppeteer","screenshots","resources","in-memory","misconception"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.md","search_terms":["mcp-puppeteer-screenshots-in-memory-only","mcp puppeteer screenshots in memory only","Puppeteer MCP screenshots live in memory only; there is no file on disk to find","Puppeteer MCP screenshots live in memory only; there is no file on disk to find fix","Puppeteer MCP screenshots live in memory only; there is no file on disk to find root cause","server-puppeteer","screenshots","resources","in-memory","misconception","mcp-server","claude-desktop","puppeteer_screenshot reports success but no image file appears on disk","the model tries to open a screenshot path and finds nothing","the agent searches the filesystem (sometimes outside the project) for the missing file","The server stores screenshots in memory and exposes them as MCP resources, with no documented filesystem path","Models often assume the screenshot was written to disk (and may claim they saved it), reinforcing the misconception","Searching the filesystem for a Puppeteer MCP screenshot","Trusting a models claim that it saved the screenshot to a path","Persist the in-memory image yourself if a file is required downstream","modelcontextprotocol/servers issue 865: Puppeteer MCP Server Missing Screenshots maintainer: screenshots are stored in memory only","Puppeteer MCP Server Missing Screenshots","Puppeteer MCP Server Missing Screenshots fix","Puppeteer MCP Server Missing Screenshots root cause"],"answer_queries":["Puppeteer MCP Server Missing Screenshots","Puppeteer MCP Server Missing Screenshots fix","Puppeteer MCP Server Missing Screenshots root cause","Puppeteer MCP screenshots live in memory only; there is no file on disk to find","Puppeteer MCP screenshots live in memory only; there is no file on disk to find fix","Puppeteer MCP screenshots live in memory only; there is no file on disk to find root cause","how to fix Puppeteer MCP screenshots live in memory only; there is no file on disk to find","mcp-server live memory there no file disk find"],"answer_summary":{"problem":"puppeteer_screenshot reports success but no image file appears on disk","root_cause":"The server stores screenshots in memory and exposes them as MCP resources, with no documented filesystem path.","fix":"Retrieve the screenshot via the MCP resource the server exposes, not from a file path.","verification":"Inspect the resource list in the client/Inspector and the filesystem."}}
{"id":"mcp-reference-server-archived-unmaintained","title":"Several official reference MCP servers are archived; their bugs will not be fixed","status":"verified","affected_tools":["mcp-server","claude-desktop","cursor"],"tags":["mcp","servers","archived","deprecated","maintenance","postgres","github","puppeteer"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.md","search_terms":["mcp-reference-server-archived-unmaintained","mcp reference server archived unmaintained","Several official reference MCP servers are archived; their bugs will not be fixed","Several official reference MCP servers are archived; their bugs will not be fixed fix","Several official reference MCP servers are archived; their bugs will not be fixed root cause","servers","archived","deprecated","maintenance","postgres","github","puppeteer","mcp-server","claude-desktop","cursor","a reference server misbehaves and the issue is closed with a deprecation/archival note","the package still installs from npm, so it looks current","a maintainer reply points to servers-archived or alternative integrations","The project archived a number of reference servers to reduce maintenance load and focus on a smaller core set","Archived packages may remain published, so an agent can install and run a server whose bugs will never be fixed","Filing or chasing bugs against an archived reference server","Assuming an npm package is maintained just because it installs and runs","modelcontextprotocol/servers issue 1219: server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived","modelcontextprotocol/servers issue 1097: maintainer deprecation notice that server-github development moved to github/github-mcp-server"],"answer_queries":["server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived","server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived fix","server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived root cause","maintainer deprecation notice that server-github development moved to github/github-mcp-server","maintainer deprecation notice that server-github development moved to github/github-mcp-server fix","maintainer deprecation notice that server-github development moved to github/github-mcp-server root cause","Several official reference MCP servers are archived; their bugs will not be fixed","Several official reference MCP servers are archived; their bugs will not be fixed fix"],"answer_summary":{"problem":"a reference server misbehaves and the issue is closed with a deprecation/archival note","root_cause":"The project archived a number of reference servers to reduce maintenance load and focus on a smaller core set.","fix":"Before debugging a reference server, check whether it is in modelcontextprotocol/servers-archived or flagged deprecated in the main README.","verification":"Check the repository of the server you depend on."}}
{"id":"mcp-reverse-proxy-buffers-sse-connection-fails","title":"A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed","status":"verified","affected_tools":["claude-desktop","mcp-server"],"tags":["mcp","sse","streamable-http","reverse-proxy","cloudflare-tunnel","buffering","remote-mcp"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.md","search_terms":["mcp-reverse-proxy-buffers-sse-connection-fails","mcp reverse proxy buffers sse connection fails","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed fix","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed root cause","streamable-http","reverse-proxy","cloudflare-tunnel","buffering","remote-mcp","claude-desktop","mcp-server","the client connects to a custom remote MCP then errors e.g. There was an error connecting to your server","server logs show success through registration, OAuth authorize, token exchange, initialize, and the SSE GET with Accept: text/event-stream, then nothing flows","direct non-proxied access works; only the proxied/tunnelled path fails","MCP Streamable HTTP streams responses over SSE, which must be flushed incrementally","A proxy/tunnel that buffers responses (Cloudflare Tunnel buffers SSE; Nginx with proxy_buffering on) holds bytes until the response completes, which never happens for a long-lived stream","So the client times out or errors despite a healthy OAuth/initialize handshake","Debugging OAuth when OAuth already succeeded and the SSE stream is what is buffered","Leaving default proxy_buffering on for an MCP streaming endpoint","Expose the MCP endpoint directly (non-proxied) for testing to confirm buffering is the cause","anthropics/claude-code issue 5826: Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize","Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize","Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize fix"],"answer_queries":["Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize","Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize fix","Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize root cause","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed fix","A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed root cause","how to fix A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed","claude-desktop breaks remote mcp after oauth initialize succeed"],"answer_summary":{"problem":"the client connects to a custom remote MCP then errors (e.g. 'There was an error connecting to your server')","root_cause":"MCP Streamable HTTP streams responses over SSE, which must be flushed incrementally.","fix":"Disable response buffering for the MCP endpoint at the proxy.","verification":"Connect through the proxy and watch the stream."}}
{"id":"mcp-server-memory-ignores-memory-file-path-env","title":"server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source","status":"verified","affected_tools":["claude-desktop","cursor","mcp-server"],"tags":["mcp","server-memory","environment-variable","npm","versioning","paths"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.md","search_terms":["mcp-server-memory-ignores-memory-file-path-env","mcp server memory ignores memory file path env","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source fix","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source root cause","server-memory","environment-variable","versioning","paths","claude-desktop","cursor","mcp-server","MEMORY_FILE_PATH is set but the memory file is created at a default location","the GitHub source handles the env var, yet the installed copy ignores it","a relative MEMORY_FILE_PATH writes to an unexpected directory","The npm release e.g. 0.6.2 was older than the GitHub main source: its compiled dist/index.js hardcoded path.join__dirname, memory.json","The repo source already read process.env.MEMORY_FILE_PATH, so reading the source misled users about installed behavior","A relative MEMORY_FILE_PATH is resolved relative to the package install directory, not the users project","Inferring installed MCP server behavior from the GitHub source instead of the published build","Assuming a relative env-var path resolves against the project working directory","Treating a node_modules patch as a permanent fix instead of upgrading","As a stopgap some users edited dist/index.js in node_modules, but upgrading the package is the durable fix","modelcontextprotocol/servers issue 1018: Environment variables not respected in @modelcontextprotocol/server-memory package","Environment variables not respected in @modelcontextprotocol/server-memory package"],"answer_queries":["Environment variables not respected in @modelcontextprotocol/server-memory package","Environment variables not respected in @modelcontextprotocol/server-memory package fix","Environment variables not respected in @modelcontextprotocol/server-memory package root cause","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source fix","server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source root cause","how to fix server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source","claude-desktop ignores file path npm build lagged source"],"answer_summary":{"problem":"MEMORY_FILE_PATH is set but the memory file is created at a default location","root_cause":"The npm release (e.g. 0.6.2) was older than the GitHub main source: its compiled dist/index.js hardcoded path.join(__dirname, 'memory.json').","fix":"Pin @modelcontextprotocol/server-memory@latest in the config to get the build that honors the env var (fix shipped in release 2025.4.25).","verification":"Launch with @latest and an absolute MEMORY_FILE_PATH, then check where the file is written."}}
{"id":"mcp-sse-received-request-before-initialization","title":"SSE MCP server: Received request before initialization was complete","status":"verified","affected_tools":["mcp-server","python-sdk"],"tags":["mcp","sse","initialization","proxy","supergateway","python-sdk","redeploy"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.md","search_terms":["mcp-sse-received-request-before-initialization","mcp sse received request before initialization","SSE MCP server: Received request before initialization was complete","SSE MCP server: Received request before initialization was complete fix","SSE MCP server: Received request before initialization was complete root cause","initialization","proxy","supergateway","python-sdk","redeploy","mcp-server","server raises RuntimeError: Received request before initialization was complete on tools/list or a tool call","appears after a redeploy/restart or when a gateway/proxy sits in front of the SSE server","the first connection worked; a later one fails","The MCP lifecycle requires the clients initialize to complete before other requests","A proxy such as supergateway sends its own initialize on launch (against spec) then forwards the clients, so the server sees initialize twice / out of order","After a redeploy the client may keep an old SSE session and send requests the fresh server never saw initialized","Wrapping the handler in a broad try/except that swallows the RuntimeError and masks other errors","Blaming the server example when the proxy violates the initialization sequence","Reconnect the client after each server restart","modelcontextprotocol/python-sdk issue 423: MCP SSE Server: Received request before initialization was complete comment confirms supergateway double-initialize; mcp-proxy works","MCP SSE Server: Received request before initialization was complete comment confirms supergateway double-initialize; mcp-proxy works","MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) fix","MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) root cause"],"answer_queries":["MCP SSE Server: Received request before initialization was complete comment confirms supergateway double-initialize; mcp-proxy works","MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) fix","MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) root cause","SSE MCP server: Received request before initialization was complete","SSE MCP server: Received request before initialization was complete fix","SSE MCP server: Received request before initialization was complete root cause","how to fix SSE MCP server: Received request before initialization was complete","mcp-server mcp server received request initialization was complete"],"answer_summary":{"problem":"server raises RuntimeError: Received request before initialization was complete on tools/list or a tool call","root_cause":"The MCP lifecycle requires the client's initialize to complete before other requests.","fix":"If a gateway/proxy is in front, use a spec-compliant one: switching supergateway -> mcp-proxy resolves the double-initialize case.","verification":"Use a compliant proxy or reconnect the client, then call tools/list."}}
{"id":"mcp-sse-session-lost-multi-worker","title":"MCP SSE session lost across workers/pods: Could not find session for ID (404)","status":"verified","affected_tools":["mcp-server","python-sdk","fastmcp"],"tags":["mcp","sse","sessions","kubernetes","gunicorn","scaling","streamable-http","python-sdk"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.md","search_terms":["mcp-sse-session-lost-multi-worker","mcp sse session lost multi worker","MCP SSE session lost across workers/pods: Could not find session for ID 404","MCP SSE session lost across workers/pods: Could not find session for ID (404) fix","MCP SSE session lost across workers/pods: Could not find session for ID (404) root cause","sessions","kubernetes","gunicorn","scaling","streamable-http","python-sdk","mcp-server","fastmcp","SSE connection opens (200), first POST returns 202, later POSTs return 404","server log: WARNING mcp.server.sse Could not find session for ID: <uuid>","deployment uses gunicorn workers > 1 or multiple replicas behind a load balancer","worse under autoscaling as pods are added/removed","The SSE transport is stateful: the session lives in the memory of the worker/pod that accepted the SSE connection","A subsequent POST /messages?session_id=... can be routed to a different worker/pod with no record of that session, returning 404","Running stateful SSE with workers > 1 or multiple replicas and no sticky routing","Hashing on $remote_addr when clients share IPs, which still splits sessions","Sticky load-balancer routing keyed on a stable per-session identifier","modelcontextprotocol/python-sdk issue 520: MCP Server Session Lost in Multi-Worker Environment comments confirm stateless_http=True and ingress sticky-hash fixes","MCP Server Session Lost in Multi-Worker Environment comments confirm stateless_http=True and ingress sticky-hash fixes"],"answer_queries":["MCP Server Session Lost in Multi-Worker Environment comments confirm stateless_http=True and ingress sticky-hash fixes","MCP Server Session Lost in Multi-Worker Environment (comments confirm stateless_http=True and ingress sticky-hash fixes) fix","MCP Server Session Lost in Multi-Worker Environment (comments confirm stateless_http=True and ingress sticky-hash fixes) root cause","MCP SSE session lost across workers/pods: Could not find session for ID 404","MCP SSE session lost across workers/pods: Could not find session for ID (404) fix","MCP SSE session lost across workers/pods: Could not find session for ID (404) root cause","how to fix MCP SSE session lost across workers/pods: Could not find session for ID 404","mcp-server lost across workers pods find id 404"],"answer_summary":{"problem":"SSE connection opens (200), first POST returns 202, later POSTs return 404","root_cause":"The SSE transport is stateful: the session lives in the memory of the worker/pod that accepted the SSE connection.","fix":"Preferred: run stateless with Streamable HTTP so no per-connection in-memory session is required.","verification":"Send repeated messages on one session under a multi-instance deployment after the change."}}
{"id":"mcp-stateless-streamable-http-closedresourceerror","title":"Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions","status":"candidate","affected_tools":["mcp-server","python-sdk","fastmcp"],"tags":["mcp","python-sdk","streamable-http","stateless","anyio","closedresourceerror","versioning"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.md","search_terms":["mcp-stateless-streamable-http-closedresourceerror","mcp stateless streamable http closedresourceerror","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions fix","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions root cause","python-sdk","streamable-http","stateless","anyio","closedresourceerror","versioning","mcp-server","fastmcp","each request raises an exception group ending in anyio.ClosedResourceError","stack passes through _handle_stateless_request / run_stateless_server / http_transport.connect() or streamable_http_manager.run_server","reproduces with stateless mode on affected versions e.g. SDK 1.12.0; FastMCP 2.10.x / 2.13.x","In affected versions the stateless Streamable HTTP path re-enters the transports read loop","On the second request the write/read stream has already been closed, so anyio raises ClosedResourceError","It is a regression in the stateless transport handling, not a problem with the users handler","Catching ClosedResourceError in your handler, which hides the transport regression","Assuming the latest SDK is always safe for stateless mode without checking the issue tracker","Stay on the last SDK version where stateless mode worked for you","modelcontextprotocol/python-sdk issue 1219: _handle_stateless_request ClosedResourceError reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13","_handle_stateless_request ClosedResourceError reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13"],"answer_queries":["_handle_stateless_request ClosedResourceError reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13","_handle_stateless_request ClosedResourceError (reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13) fix","_handle_stateless_request ClosedResourceError (reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13) root cause","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions fix","Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions root cause","how to fix Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions","mcp-server server throws anyio closedresourceerror some sdk versions"],"answer_summary":{"problem":"each request raises an exception group ending in anyio.ClosedResourceError","root_cause":"In affected versions the stateless Streamable HTTP path re-enters the transport's read loop.","fix":"Pin a known-good SDK version; users reported 1.11.0 working where 1.12.0 failed.","verification":"Send repeated requests to the stateless server on the pinned/fixed version."}}
{"id":"mcp-stdio-server-exits-shell-path-not-inherited","title":"MCP stdio server exits immediately because the GUI client does not inherit your shell PATH","status":"verified","affected_tools":["claude-desktop","mcp-server"],"tags":["mcp","stdio","path","environment","nvm","npx","macos","claude-desktop","transport"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.md","search_terms":["mcp-stdio-server-exits-shell-path-not-inherited","mcp stdio server exits shell path not inherited","MCP stdio server exits immediately because the GUI client does not inherit your shell PATH","MCP stdio server exits immediately because the GUI client does not inherit your shell PATH fix","MCP stdio server exits immediately because the GUI client does not inherit your shell PATH root cause","stdio","path","environment","macos","claude-desktop","transport","mcp-server","client log: Server transport closed unexpectedly, this is likely due to the process exiting early","client log shows write EPIPE immediately after the client initialize message","the same command starts fine when run manually in the terminal","a Node version manager (NVM, fnm, asdf) is in use, or node/npx live outside /usr/bin","the client uses an unexpected or missing Node version","GUI clients launch MCP servers without sourcing the users shell config, so the child gets a minimal PATH","With NVM/fnm/asdf the versioned node directory is not on that PATH, so npx/node is missing or wrong and the server exits at spawn","The client already sent initialize; the dying server writing to the closed pipe surfaces as write EPIPE and transport closed / process exiting early","The MCP server package itself is usually fine","Reinstalling or switching the server package when the package is fine","Treating write EPIPE as a server crash instead of a bad launch environment","Relying on bare npx/node in a GUI-launched config while using NVM/fnm/asdf"],"answer_queries":["MCP Servers Dont Work with NVM","MCP Servers Dont Work with NVM fix","MCP Servers Dont Work with NVM root cause","npx-for-claude wrapper workaround 66 reactions","npx-for-claude wrapper workaround (66 reactions) fix","npx-for-claude wrapper workaround (66 reactions) root cause","Server transport closed unexpectedly, process exiting early write EPIPE","Server transport closed unexpectedly, process exiting early (write EPIPE) fix"],"answer_summary":{"problem":"client log: Server transport closed unexpectedly, this is likely due to the process exiting early","root_cause":"GUI clients launch MCP servers without sourcing the user's shell config, so the child gets a minimal PATH.","fix":"Confirm the failure is launch-environment, not a broken server: it runs in your terminal but fails when the client launches it.","verification":"Inspect the client MCP log after a full restart."}}
{"id":"mcp-stdio-stdout-logging-breaks-protocol","title":"Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream","status":"verified","affected_tools":["mcp-server","typescript-sdk","python-sdk"],"tags":["mcp","stdio","stdout","logging","json-rpc","console-log","protocol"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.md","search_terms":["mcp-stdio-stdout-logging-breaks-protocol","mcp stdio stdout logging breaks protocol","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream fix","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream root cause","stdio","stdout","logging","json-rpc","console-log","protocol","mcp-server","typescript-sdk","python-sdk","client error SyntaxError: ... is not valid JSON inside deserializeMessage / JSON.parse","the bad token matches the servers own log text e.g. get_weather tool called","tool calls fail intermittently, correlated with code paths that log","In the stdio transport, stdout is the JSON-RPC channel","A server writing human-readable output to stdout (console.log in Node, print in Python) injects non-JSON lines between protocol messages","The clients line-based deserializer then tries to JSON.parse the log text and throws","Using console.log / bare print for debugging inside a stdio MCP server","A dependency or startup banner that prints to stdout in a stdio server","Temporarily disable logging in the server to confirm the diagnosis","modelcontextprotocol/typescript-sdk issue 244: SyntaxError in stdio deserializeMessage a console.log in the server triggers it"],"answer_queries":["SyntaxError in stdio deserializeMessage a console.log in the server triggers it","SyntaxError in stdio deserializeMessage (a console.log in the server triggers it) fix","SyntaxError in stdio deserializeMessage (a console.log in the server triggers it) root cause","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream fix","Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream root cause","how to fix Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream","mcp-server stdio mcp server corrupts json rpc stream"],"answer_summary":{"problem":"client error SyntaxError: ... is not valid JSON inside deserializeMessage / JSON.parse","root_cause":"In the stdio transport, stdout is the JSON-RPC channel.","fix":"Remove or redirect all stdout writes in the server; use stderr.","verification":"Call a tool after moving logging to stderr."}}
{"id":"mcp-streamable-http-client-no-oauth-on-401","title":"Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow","status":"verified","affected_tools":["mcp-inspector","mcp-server"],"tags":["mcp","streamable-http","oauth","401","inspector","authorization","transport"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.md","search_terms":["mcp-streamable-http-client-no-oauth-on-401","mcp streamable http client no oauth on 401","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow fix","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow root cause","streamable-http","oauth","inspector","authorization","transport","mcp-inspector","mcp-server","connecting to an OAuth-protected MCP server over Streamable HTTP hangs","log shows Error from MCP server: Error: Error POSTing to endpoint (HTTP 401) then no further progress","the same server triggers the browser OAuth flow correctly via the SSE transport","The SSE client transport detected a 401 and started authorization","The Streamable HTTP client transport did not handle the 401 as an auth challenge, so no OAuth flow started and the connection stalled","It is a client/transport bug, not a server misconfiguration","Concluding the OAuth server is broken when the client transport did not act on the 401","Staying on an old client version that lacks Streamable HTTP auth handling","Use the SSE transport temporarily if it handles the OAuth challenge while you upgrade","modelcontextprotocol/inspector issue 358: When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 resolved in a released Inspector version","When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 resolved in a released Inspector version","When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 (resolved in a released Inspector version) fix"],"answer_queries":["When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 resolved in a released Inspector version","When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 (resolved in a released Inspector version) fix","When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 (resolved in a released Inspector version) root cause","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow fix","Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow root cause","how to fix Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow","mcp-inspector client hangs 401 instead starting oauth flow"],"answer_summary":{"problem":"connecting to an OAuth-protected MCP server over Streamable HTTP hangs","root_cause":"The SSE client transport detected a 401 and started authorization.","fix":"Upgrade to a client/Inspector/SDK version where Streamable HTTP triggers OAuth on 401 (resolved in a released Inspector version).","verification":"Connect over Streamable HTTP to an OAuth-protected server on the fixed client."}}
{"id":"mcp-time-server-invalid-local-timezone","title":"mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST","status":"verified","affected_tools":["mcp-server","claude-desktop"],"tags":["mcp","server-time","timezone","zoneinfo","iana","uvx"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.md","search_terms":["mcp-time-server-invalid-local-timezone","mcp time server invalid local timezone","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST fix","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST root cause","server-time","timezone","zoneinfo","iana","mcp-server","claude-desktop","uvx mcp-server-time traceback through zoneinfo/_common.py load_tzdata failing to load the timezone","happens when DST is active and the local zone shows as an abbreviation EDT/PDT/CEST","works fine in standard time for some users","The server resolves the local timezone, but the platform reports a non-IANA abbreviation e.g. EDT","Pythons zoneinfo only loads canonical IANA names (e.g. America/New_York), so loading the abbreviation raises and the server fails to start","Passing a timezone abbreviation (EDT/PDT/CEST) instead of an IANA name","Relying on auto-detected local timezone on a platform that emits abbreviations during DST","Set the process/system timezone to a canonical IANA name","modelcontextprotocol/servers issue 786: Time server fails under EDT timezone use --local-timezone with an IANA name","Time server fails under EDT timezone use --local-timezone with an IANA name","Time server fails under EDT timezone (use --local-timezone with an IANA name) fix","Time server fails under EDT timezone (use --local-timezone with an IANA name) root cause","how to fix mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST"],"answer_queries":["Time server fails under EDT timezone use --local-timezone with an IANA name","Time server fails under EDT timezone (use --local-timezone with an IANA name) fix","Time server fails under EDT timezone (use --local-timezone with an IANA name) root cause","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST fix","mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST root cause","how to fix mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST","mcp-server local timezone abbreviation like edt pdt cest"],"answer_summary":{"problem":"uvx mcp-server-time traceback through zoneinfo/_common.py load_tzdata failing to load the timezone","root_cause":"The server resolves the local timezone, but the platform reports a non-IANA abbreviation (e.g. EDT).","fix":"Pass an explicit IANA timezone with --local-timezone.","verification":"Start the server with an explicit IANA timezone."}}
{"id":"mcp-ts-client-default-60s-request-timeout","title":"MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress","status":"verified","affected_tools":["mcp-server","typescript-sdk"],"tags":["mcp","typescript-sdk","timeout","error-32001","progress","long-running"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.md","search_terms":["mcp-ts-client-default-60s-request-timeout","mcp ts client default 60s request timeout","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress fix","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress root cause","typescript-sdk","timeout","error-32001","progress","long-running","mcp-server","McpError: MCP error -32001: Request timed out with data: { timeout: 60000 }","the tool finishes fine from the Python client but times out from the TS/JS client","setting a timeout on connect alone does not help","the server sends periodic progress yet the client gives up at 60s","The default per-request timeout is 60000 ms","Progress notifications only extend it when resetTimeoutOnProgress is enabled","The timeout must be set in the per-request options passed to callTool, not only on connect/transport","Setting timeout only on connect and expecting per-call requests to inherit it","Relying on server progress without resetTimeoutOnProgress: true","Break very long operations into shorter calls if you cannot stream progress","modelcontextprotocol/typescript-sdk issue 245: mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress","mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress","mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress fix"],"answer_queries":["mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress","mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress fix","mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress root cause","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress fix","MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress root cause","how to fix MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress","mcp-server after 60s 32001 unless you reset progress"],"answer_summary":{"problem":"McpError: MCP error -32001: Request timed out with data: { timeout: 60000 }","root_cause":"The default per-request timeout is 60000 ms.","fix":"Pass request options as the third argument to callTool with a larger timeout and resetTimeoutOnProgress: true.","verification":"Run a tool call that exceeds 60 seconds with the options set."}}
{"id":"mcp-ts-sdk-commonjs-esm-pkce-challenge","title":"MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge)","status":"verified","affected_tools":["mcp-server","typescript-sdk"],"tags":["mcp","typescript-sdk","commonjs","esm","nestjs","pkce-challenge","dependencies"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.md","search_terms":["mcp-ts-sdk-commonjs-esm-pkce-challenge","mcp ts sdk commonjs esm pkce challenge","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM pkce-challenge","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) fix","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) root cause","typescript-sdk","commonjs","nestjs","pkce-challenge","dependencies","mcp-server","runtime crash on MCP client init: ERR_REQUIRE_ESM: require() of ES Module pkce-challenge is not supported. Use dynamic import() instead","the project is CommonJS often NestJS","the error originates inside @modelcontextprotocol/sdk/dist/cjs/client/auth.js","pkce-challenge shipped as ESM-only","The SDKs CommonJS build used a static require(pkce-challenge), which Node refuses for an ESM-only module from CJS, throwing at load time","Pinning a very old SDK (e.g. 1.5.0) just to avoid pkce-challenge, losing later fixes","Patching node_modules as a permanent solution instead of upgrading or using overrides","Use package-manager overrides to pin pkce-challenge@5.0.0","Temporarily import from the SDKs ESM dist","modelcontextprotocol/typescript-sdk issue 217: @modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency pkce-challenge","crouchcd/pkce-challenge release 5.0.0 referenced as a compatible version","@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency pkce-challenge","@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge) fix"],"answer_queries":["@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency pkce-challenge","@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge) fix","@modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge) root cause","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM pkce-challenge","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) fix","MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) root cause","how to fix MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM pkce-challenge","mcp-server commonjs projects err require esm pkce challenge"],"answer_summary":{"problem":"runtime crash on MCP client init: ERR_REQUIRE_ESM: require() of ES Module pkce-challenge is not supported. Use dynamic import() instead","root_cause":"pkce-challenge shipped as ESM-only.","fix":"Upgrade @modelcontextprotocol/sdk to a version that lazily import()s pkce-challenge.","verification":"Start the CommonJS app and initialize the MCP client."}}
{"id":"mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror","title":"MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation)","status":"candidate","affected_tools":["mcp-server","typescript-sdk"],"tags":["mcp","typescript-sdk","cloudflare-workers","edge","ajv","elicitation","evalerror"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.md","search_terms":["mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror","mcp ts sdk edge runtime ajv codegen evalerror","MCP TS SDK validation fails on Cloudflare Workers with EvalError AJV code generation","MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) fix","MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) root cause","typescript-sdk","cloudflare-workers","edge","elicitation","evalerror","mcp-server","EvalError: Code generation from strings disallowed for this context, with a stack through new Function and Ajv.localCompile","occurs on Cloudflare Workers or other no-eval edge runtimes, not on Node","triggered by schema validation, e.g. after responding to an elicitInput request","The SDK validates JSON Schema with AJV v6, which generates validator code at runtime via new Function","Edge runtimes such as Cloudflare Workers disallow dynamic code generation from strings, so validator construction throws EvalError","Assuming Node-tested MCP server code runs unchanged on Cloudflare Workers","Calling elicitation on mcpServer.server instead of Cloudflares McpAgent","Move schema validation to a Node-hosted component if the edge runtime cannot run the validator","modelcontextprotocol/typescript-sdk issue 689: Elicitation feature fails on Cloudflare Workers due to AJV code generation EvalError","Cloudflare changelog: MCP elicitation support on McpAgent","Elicitation feature fails on Cloudflare Workers due to AJV code generation EvalError","Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) fix","Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) root cause"],"answer_queries":["Elicitation feature fails on Cloudflare Workers due to AJV code generation EvalError","Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) fix","Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) root cause","MCP TS SDK validation fails on Cloudflare Workers with EvalError AJV code generation","MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) fix","MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) root cause","how to fix MCP TS SDK validation fails on Cloudflare Workers with EvalError AJV code generation","mcp-server fails cloudflare workers evalerror ajv code generation"],"answer_summary":{"problem":"EvalError: Code generation from strings disallowed for this context, with a stack through new Function and Ajv.localCompile","root_cause":"The SDK validates JSON Schema with AJV v6, which generates validator code at runtime via new Function.","fix":"On Cloudflare, use the McpAgent integration that added elicitation support; call elicitation on the McpAgent class, not mcpServer.server.","verification":"Run the validation/elicitation path on the edge runtime."}}
{"id":"mcp-ts-sdk-type-instantiation-excessively-deep","title":"MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE","status":"verified","affected_tools":["mcp-server","typescript-sdk"],"tags":["mcp","typescript-sdk","zod","typescript","tsconfig","type-error","ide"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.md","search_terms":["mcp-ts-sdk-type-instantiation-excessively-deep","mcp ts sdk type instantiation excessively deep","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE fix","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE root cause","typescript-sdk","typescript","tsconfig","type-error","mcp-server","Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types","the TypeScript server in Cursor/VS Code hangs and saving files stalls","it appears intermittently; @ts-ignore silences the error but not the slowdown","Deep generic instantiation in Zod's types as consumed by the SDK's tool typings","Worsened by multiple resolved Zod versions, a legacy moduleResolution: 'node' tsconfig, and certain SDK versions reported from >=1.16.0","Suppressing with @ts-ignore and ignoring the language-server slowdown","Leaving two Zod versions in the dependency tree","Pin a known-good SDK + Zod pair until you can update tsconfig/Zod","modelcontextprotocol/typescript-sdk issue 494: 'Type instantiation is excessively deep' when importing ToolCallback Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6","Type instantiation is excessively deep when importing ToolCallback Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6","Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) fix","Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) root cause","how to fix MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE","mcp-server type instantiation excessively deep ts2589 freezes ide"],"answer_queries":["Type instantiation is excessively deep when importing ToolCallback Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6","Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) fix","Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) root cause","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE fix","MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE root cause","how to fix MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE","mcp-server type instantiation excessively deep ts2589 freezes ide"],"answer_summary":{"problem":"Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types","root_cause":"Deep generic instantiation in Zod's types as consumed by the SDK's tool typings.","fix":"Ensure a single Zod version is installed; duplicates are a common trigger.","verification":"Reopen the project and reference SDK tool types after the change."}}
{"id":"mcp-ts-sdk-zod-v4-incompatible","title":"MCP TypeScript SDK breaks with Zod v4: w._parse is not a function","status":"verified","affected_tools":["mcp-server","typescript-sdk"],"tags":["mcp","typescript-sdk","zod","dependencies","versioning","tools"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.md","search_terms":["mcp-ts-sdk-zod-v4-incompatible","mcp ts sdk zod v4 incompatible","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function fix","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function root cause","typescript-sdk","dependencies","versioning","tools","mcp-server","tool execution returns {\"code\":-32603,\"message\":\"w._parse is not a function...\"}","tools/list fails with null is not an object evaluating F._def","errors appear in minified code and are hard to trace","Zod was recently upgraded to v4.x","MCP SDK versions up to ~1.17.5 declare zod ^3.x and call Zod internal API _def, _parse","Zod v4 changed those internal structures, so the SDKs calls hit undefined methods at runtime when a v4 Zod is resolved","Mixing a Zod-v4 project with an SDK that only supports Zod v3","Leaving two Zod versions in the tree and assuming the right one resolves","Stay on Zod v3 until the SDK upgrade is feasible","modelcontextprotocol/typescript-sdk issue 925: MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes maintainer notes 1.23.0-beta adds v4 support","MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes","MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes fix","MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes root cause","how to fix MCP TypeScript SDK breaks with Zod v4: w._parse is not a function"],"answer_queries":["MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes","MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes fix","MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes root cause","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function fix","MCP TypeScript SDK breaks with Zod v4: w._parse is not a function root cause","how to fix MCP TypeScript SDK breaks with Zod v4: w._parse is not a function","mcp-server typescript sdk breaks zod v4 parse function"],"answer_summary":{"problem":"tool execution returns {\"code\":-32603,\"message\":\"w._parse is not a function...\"}","root_cause":"MCP SDK versions up to ~1.17.5 declare zod ^3.x and call Zod internal API (_def, _parse).","fix":"Quick unblock: pin Zod v3 and ensure a single Zod version resolves.","verification":"Check the resolved Zod version and re-run a tool call."}}
{"id":"mcp-windows-npx-requires-cmd-c-wrapper","title":"On Windows an MCP server launched with npx needs a cmd /c wrapper","status":"verified","affected_tools":["claude-desktop","cursor","cline","mcp-server"],"tags":["mcp","windows","npx","cmd","spawn","enoent","startup"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.md","search_terms":["mcp-windows-npx-requires-cmd-c-wrapper","mcp windows npx requires cmd c wrapper","On Windows an MCP server launched with npx needs a cmd /c wrapper","On Windows an MCP server launched with npx needs a cmd /c wrapper fix","On Windows an MCP server launched with npx needs a cmd /c wrapper root cause","windows","spawn","enoent","startup","claude-desktop","cursor","cline","mcp-server","Windows only: the MCP server will not start","logs show spawn npx ENOENT or locale text equivalent to npx is not recognized as an internal or external command","the same npx command runs fine in PowerShell or cmd manually","On Windows npx and npm are npx.cmd / npm.cmd batch files, not executables","Nodes spawn without a shell cannot execute a .cmd directly, so command: npx yields ENOENT","Routing through cmd /c lets the Windows command interpreter resolve and run the shim","Using bare command: 'npx' on Windows","Assuming a macOS/Linux config is portable to Windows without cmd /c","Use the absolute node.exe path plus the server script path instead of npx","modelcontextprotocol/servers issue 1097: Windows npx launch failure with garbled 'not recognized' error -32000","modelcontextprotocol/servers issue 891: comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions"],"answer_queries":["Windows npx launch failure with garbled 'not recognized' error -32000","Windows npx launch failure with garbled 'not recognized' error (-32000) fix","Windows npx launch failure with garbled 'not recognized' error (-32000) root cause","comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions","comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions fix","comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions root cause","On Windows an MCP server launched with npx needs a cmd /c wrapper","On Windows an MCP server launched with npx needs a cmd /c wrapper fix"],"answer_summary":{"problem":"Windows only: the MCP server will not start","root_cause":"On Windows npx and npm are npx.cmd / npm.cmd batch files, not executables.","fix":"Launch through cmd: set command to 'cmd' and args to ['/c','npx','-y','<package>', ...].","verification":"Relaunch after wrapping with cmd /c."}}
{"id":"portaudio-stream-close-blocks-hotkey-callback-thread","title":"PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener","status":"verified","affected_tools":["portaudio","pynput","voice-to-claude"],"tags":["macos","audio","portaudio","pynput","threading","hotkey","deadlock","voice"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.md","search_terms":["portaudio-stream-close-blocks-hotkey-callback-thread","portaudio stream close blocks hotkey callback thread","PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener","PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener fix","PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener root cause","macos","audio","portaudio","pynput","threading","hotkey","deadlock","voice","voice-to-claude","a push-to-talk dictation daemon intermittently goes unresponsive after switching windows and dictating","the log is stuck at 'Recording stopped, processing...' with no following 'Audio duration' line","daemon status still reports Running but pressing the hotkey does nothing","only a daemon restart recovers it","stop()/close() of a PortAudio stream on a flaky/display-connected device can block for a long time","It was being called inline inside the pynput key-release callback, which runs on the single listener thread","The blocking call wedged that thread, so the global hotkey stopped firing and the whole daemon appeared hung even though the process stayed alive","Doing blocking audio teardown or processing inline in a global-hotkey callback","Trusting 'process is Running' as proof the hotkey listener is still alive","Add a watchdog that restarts the listener if the hotkey stops responding"],"answer_queries":["PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener","PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener fix","PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener root cause","how to fix PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener","portaudio close hotkey callback thread freeze global listener","portaudio close hotkey callback thread freeze global listener fix","freeze global listener stream stop close hotkey callback thread portaudio","freeze global listener stream stop close hotkey callback thread portaudio fix"],"answer_summary":{"problem":"a push-to-talk dictation daemon intermittently goes unresponsive after switching windows and dictating","root_cause":"stop()/close() of a PortAudio stream on a flaky/display-connected device can block for a long time.","fix":"Move recorder.stop() (the PortAudio stream.stop()/close() calls) AND all downstream processing off the pynput key-release callback thread into a background thread.","verification":"Use the daemon heavily across multiple windows after the change."}}
{"id":"pynput-mixed-cjk-ascii-type-out-of-order-macos","title":"pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste","status":"verified","affected_tools":["pynput","voice-to-claude"],"tags":["macos","pynput","text-injection","unicode","cjk","race-condition","clipboard","voice"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.md","search_terms":["pynput-mixed-cjk-ascii-type-out-of-order-macos","pynput mixed cjk ascii type out of order macos","pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste","pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste fix","pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste root cause","macos","pynput","text-injection","unicode","race-condition","clipboard","voice","voice-to-claude","injecting '打开Claude Code，然后commit一下。' yields '打开ClaudeC，然后一下。odecomit' — reordered, English fragments shoved to the end, some CJK dropped","pure-English and pure-Chinese strings inject fine","only mixed CJK+ASCII text scrambles","On macOS pynput types CJK characters via synthesized Unicode events and ASCII via key events","The two dispatch paths have different timing and race each other, so a fast mixed-script string arrives interleaved / reordered","Using pynput Controller.type() for mixed CJK+ASCII text on macOS","Adding per-character sleeps to 'fix' ordering instead of switching to an atomic paste","Restore the previous clipboard contents after pasting if clobbering it is a concern","voice-to-claude daemon debugging session","how to fix pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste","pynput mixed chinese english text macos clipboard paste"],"answer_queries":["pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste","pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste fix","pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste root cause","how to fix pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste","pynput mixed chinese english text macos clipboard paste","pynput mixed chinese english text macos clipboard paste fix","macos clipboard paste type scrambles mixed chinese english text pynput","macos clipboard paste type scrambles mixed chinese english text pynput fix"],"answer_summary":{"problem":"injecting '打开Claude Code，然后commit一下。' yields '打开ClaudeC，然后一下。odecomit' — reordered, English fragments shoved to the end, some CJK dropped","root_cause":"On macOS pynput types CJK characters via synthesized Unicode events and ASCII via key events.","fix":"Switch text injection from per-character keyboard.type() to clipboard paste: copy the full string via pbcopy, then simulate Cmd+V.","verification":"Inject the same mixed Chinese+English sentence after the change."}}
{"id":"uv-cache-outside-workspace-sandbox","title":"uv fails in a managed workspace because cache or Python install paths are outside writable roots","status":"verified","affected_tools":["codex","claude-code","gemini","qwen-code","cursor","aider"],"tags":["python","uv","sandbox","cache"],"url":"https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html","markdown_url":"https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.md","search_terms":["uv-cache-outside-workspace-sandbox","uv cache outside workspace sandbox","uv fails in a managed workspace because cache or Python install paths are outside writable roots","uv fails in a managed workspace because cache or Python install paths are outside writable roots fix","uv fails in a managed workspace because cache or Python install paths are outside writable roots root cause","In managed agent sandboxes, uv may fail because its default cache or Python install directories are not writable; point them to workspace-local paths","python","sandbox","cache","codex","claude-code","gemini","qwen-code","cursor","aider","uv run or uv sync fails with permission or sandbox filesystem errors","the project directory is writable but global cache paths are not","setting UV_CACHE_DIR and UV_PYTHON_INSTALL_DIR inside the workspace allows progress","uv defaults to cache or interpreter directories outside the agents writable roots","Changing project code to avoid uv before checking cache permissions","Using global chmod or deleting user-level caches from an agent session","Use an existing project virtual environment if it is already present and writable","Ask for sandbox escalation only when dependency downloads or outside-workspace writes are truly required","Agent Pitbook bootstrap local session"],"answer_queries":["uv fails in a managed workspace because cache or Python install paths are outside writable roots","uv fails in a managed workspace because cache or Python install paths are outside writable roots fix","uv fails in a managed workspace because cache or Python install paths are outside writable roots root cause","how to fix uv fails in a managed workspace because cache or Python install paths are outside writable roots","codex workspace cache python install paths writable roots","codex workspace cache python install paths writable roots fix","paths writable roots fails managed workspace cache python install codex","paths writable roots fails managed workspace cache python install codex fix"],"answer_summary":{"problem":"uv run or uv sync fails with permission or sandbox filesystem errors","root_cause":"uv defaults to cache or interpreter directories outside the agent's writable roots.","fix":"Set UV_CACHE_DIR to a workspace-local directory.","verification":"Run a small uv command with local paths."}}