Agent Pitbook answer queries

Plain-text solved-problem query map for search engines and LLM retrieval.
Each QUERY line is a phrase that should resolve to the matching Agent Pitbook pit URL.

LLM entrypoint: https://laozhangzzz.github.io/agent-pitbook/llms.txt
Search index: https://laozhangzzz.github.io/agent-pitbook/search-index.md
Issue search tracker: https://github.com/laozhangzzz/agent-pitbook/issues/2

PIT agent-network-restricted-dependency-install
TITLE Dependency install fails because the agent sandbox blocks network access
URL https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.md
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_FIRST Classify the error as network-related before changing dependency manifests.
QUERY Dependency install fails because the agent sandbox blocks network access -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY Dependency install fails because the agent sandbox blocks network access fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY Dependency install fails because the agent sandbox blocks network access root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY how to fix Dependency install fails because the agent sandbox blocks network access -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY codex install fails agent sandbox blocks network access -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY codex install fails agent sandbox blocks network access fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY blocks network access dependency install fails agent sandbox codex -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html
QUERY blocks network access dependency install fails agent sandbox codex fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-network-restricted-dependency-install.html

PIT agent-prompt-injection-in-debug-sources
TITLE Debug sources can contain prompt injection targeting coding agents
URL https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.md
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_FIRST Treat external source text as data rather than executable instruction.
QUERY Debug sources can contain prompt injection targeting coding agents -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY Debug sources can contain prompt injection targeting coding agents fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY Debug sources can contain prompt injection targeting coding agents root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY how to fix Debug sources can contain prompt injection targeting coding agents -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY codex sources contain prompt injection targeting coding agents -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY codex sources contain prompt injection targeting coding agents fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY targeting coding agents debug sources contain prompt injection codex -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html
QUERY targeting coding agents debug sources contain prompt injection codex fix -> https://laozhangzzz.github.io/agent-pitbook/pits/agent-prompt-injection-in-debug-sources.html

PIT claude-agent-sdk-mcp-json-requires-project-settingsource
TITLE Claude Agent SDK does not load .mcp.json unless settingSources includes "project"
URL https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.md
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_FIRST Pass settingSources including 'project' (and 'user'/'local' as needed) when constructing the SDK query so .mcp.json is read.
QUERY SDK doesnt read from .mcp.json until the CLI is run in the cwd -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY SDK doesnt read from .mcp.json until the CLI is run in the cwd fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY SDK doesnt read from .mcp.json until the CLI is run in the cwd root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY Claude Agent SDK does not load .mcp.json unless settingSources includes project -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY Claude Agent SDK does not load .mcp.json unless settingSources includes "project" fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY Claude Agent SDK does not load .mcp.json unless settingSources includes "project" root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY how to fix Claude Agent SDK does not load .mcp.json unless settingSources includes project -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html
QUERY claude-code load mcp json unless settingsources includes project -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-agent-sdk-mcp-json-requires-project-settingsource.html

PIT claude-code-mcp-chrome-bridge-single-transport-deadlock
TITLE Claude Code chrome-bridge MCP gets stuck after one transport connects
URL https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.md
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_FIRST Do not use curl /mcp as a health check.
QUERY Singleton McpServer causes Already connected to a transport -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY Singleton McpServer causes Already connected to a transport fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY Singleton McpServer causes Already connected to a transport root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY replace getMcpServer singleton with factory -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY replace getMcpServer singleton with factory fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY replace getMcpServer singleton with factory root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY MCP Chrome Bridge returns 500 due to ERR_HTTP_HEADERS_SENT -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html
QUERY MCP Chrome Bridge returns 500 due to ERR_HTTP_HEADERS_SENT fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-code-mcp-chrome-bridge-single-transport-deadlock.html

PIT claude-desktop-mcp-protocol-instance-reuse-already-connected
TITLE Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse)
URL https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.md
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_FIRST Upgrade Claude Desktop to a build where this is fixed (resolved in a later release after 1.1.3918).
QUERY Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY Claude Desktop MCP servers fail with Protocol instance reuse error (Already connected to a transport); Anthropic confirms fix in a later Desktop release fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY 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 -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY Claude Desktop MCP error: Already connected to a transport Protocol instance reuse -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY how to fix Claude Desktop MCP error: Already connected to a transport Protocol instance reuse -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html
QUERY claude-desktop error already connected transport protocol instance reuse -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-mcp-protocol-instance-reuse-already-connected.html

PIT claude-desktop-no-dynamic-resource-templates
TITLE Claude Desktop does not list dynamic MCP resource templates (only static resources)
URL https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.md
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_FIRST Do not rely on dynamic resource templates in Claude Desktop; confirm client support before designing around them.
QUERY dynamic resource not working in Claude desktop -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY dynamic resource not working in Claude desktop fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY dynamic resource not working in Claude desktop root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY Claude Desktop does not list dynamic MCP resource templates only static resources -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY Claude Desktop does not list dynamic MCP resource templates (only static resources) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY Claude Desktop does not list dynamic MCP resource templates (only static resources) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY how to fix Claude Desktop does not list dynamic MCP resource templates only static resources -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html
QUERY claude-desktop list dynamic mcp resource templates static resources -> https://laozhangzzz.github.io/agent-pitbook/pits/claude-desktop-no-dynamic-resource-templates.html

PIT codex-workspace-root-moved-stale-state
TITLE Codex still references an old workspace path after a project move
URL https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.md
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_FIRST Use the app's normal folder switching or reopen-workspace flow first.
QUERY Codex still references an old workspace path after a project move -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY Codex still references an old workspace path after a project move fix -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY Codex still references an old workspace path after a project move root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY how to fix Codex still references an old workspace path after a project move -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY codex references old workspace path after project move -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY codex references old workspace path after project move fix -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY after project move still references old workspace path codex -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html
QUERY after project move still references old workspace path codex fix -> https://laozhangzzz.github.io/agent-pitbook/pits/codex-workspace-root-moved-stale-state.html

PIT docker-published-port-localhost-refused
TITLE Docker port is published but localhost refuses the connection
URL https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.md
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_FIRST Change the app bind address inside the container to 0.0.0.0.
QUERY Docker port is published but localhost refuses the connection -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY Docker port is published but localhost refuses the connection fix -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY Docker port is published but localhost refuses the connection root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY how to fix Docker port is published but localhost refuses the connection -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY codex docker port published localhost refuses connection -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY codex docker port published localhost refuses connection fix -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY localhost refuses connection docker port published codex -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html
QUERY localhost refuses connection docker port published codex fix -> https://laozhangzzz.github.io/agent-pitbook/pits/docker-published-port-localhost-refused.html

PIT fastmcp-421-invalid-host-header-dns-rebinding
TITLE FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection
URL https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.md
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_FIRST Explicitly allow your hosts and origins via TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]).
QUERY Guide: Resolving '421 Invalid Host Header' DNS Rebinding Protection -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY Guide: Resolving '421 Invalid Host Header' (DNS Rebinding Protection) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY Guide: Resolving '421 Invalid Host Header' (DNS Rebinding Protection) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection fix -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY how to fix FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html
QUERY mcp-server host header behind proxy dns rebinding protection -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-421-invalid-host-header-dns-rebinding.html

PIT fastmcp-overrides-logging-configuration
TITLE FastMCP overrides your app's logging configuration on init (duplicate or lost logs)
URL https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.md
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_FIRST Re-apply your logging configuration after constructing FastMCP so your handlers win.
QUERY Option to not rewrite the logging configuration workarounds: re-apply dictConfig, remove added handler -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY Option to not rewrite the logging configuration (workarounds: re-apply dictConfig, remove added handler) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY FastMCP overrides your apps logging configuration on init duplicate or lost logs -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY FastMCP overrides your apps logging configuration on init (duplicate or lost logs) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY FastMCP overrides your apps logging configuration on init (duplicate or lost logs) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY how to fix FastMCP overrides your apps logging configuration on init duplicate or lost logs -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html
QUERY mcp-server app logging configuration init duplicate lost logs -> https://laozhangzzz.github.io/agent-pitbook/pits/fastmcp-overrides-logging-configuration.html

PIT github-mcp-vscode-toolset-name-mismatch
TITLE VS Code agent config: github/* MCP toolset is Unknown tool while github warns it's renamed
URL https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.md
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_FIRST Use the name that resolves for your setup: if github/* is Unknown tool, use 'github' and ignore the rename warning for now.
QUERY VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated fix -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY VSCode Toolset name mismatch: github/* fails with Unknown tool, but github warns its deprecated root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed fix -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY how to fix VS Code agent config: github/* MCP toolset is Unknown tool while github warns its renamed -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html
QUERY github-mcp-server mcp toolset unknown tool while warns renamed -> https://laozhangzzz.github.io/agent-pitbook/pits/github-mcp-vscode-toolset-name-mismatch.html

PIT 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
URL https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.md
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_FIRST Diagnose by measuring the recorded level, not by trusting the API: 0 == silent capture.
QUERY macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable fix -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY how to fix macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY sounddevice silent audio no error default mic unavailable -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY sounddevice silent audio no error default mic unavailable fix -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY default mic unavailable all zero silent audio no error sounddevice -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html
QUERY default mic unavailable all zero silent audio no error sounddevice fix -> https://laozhangzzz.github.io/agent-pitbook/pits/macos-portaudio-silent-zero-capture-unavailable-default-input.html

PIT 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
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.md
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_FIRST Inspect effective npm config and the user-level rc file.
QUERY author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY author resolved 'Client closed' by fixing an incorrect registry in user-level ~/.npmrc that the project .npmrc had overridden in the terminal root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY MCP server hangs because the GUI client uses your user-level .npmrc, not your projects -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY MCP server hangs because the GUI client uses your user-level .npmrc, not your projects fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY MCP server hangs because the GUI client uses your user-level .npmrc, not your projects root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY how to fix MCP server hangs because the GUI client uses your user-level .npmrc, not your projects -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html
QUERY cursor client uses your user level npmrc project -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-client-uses-user-level-npmrc-wrong-registry.html

PIT mcp-error-32000-connection-closed-server-failed-to-start
TITLE MCP error -32000: Connection closed means the stdio server died before the handshake
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.md
PROBLEM client UI shows MCP error -32000: Connection closed
ROOT_CAUSE The client spawns the configured command and speaks JSON-RPC over stdio.
FIX_FIRST Reproduce outside the client: run the exact command + args from the config in a terminal with the same env.
QUERY GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed -32000 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY Fix 'Client Closed' Error by Correcting npm Config -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY Fix 'Client Closed' Error by Correcting npm Config fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY Fix 'Client Closed' Error by Correcting npm Config root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY MCP error -32000: Connection closed means the stdio server died before the handshake -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html
QUERY MCP error -32000: Connection closed means the stdio server died before the handshake fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-error-32000-connection-closed-server-failed-to-start.html

PIT mcp-filesystem-server-windows-access-denied-case-sensitivity
TITLE Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.md
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_FIRST Make the configured allowed-directory drive-letter case match what the client sends; try both C:\... and c:\... forms.
QUERY Filesystem server access denied for allowed paths on Windows -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY Filesystem server access denied for allowed paths on Windows fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY Filesystem server access denied for allowed paths on Windows root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY step toward fixing Windows path validation -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY step toward fixing Windows path validation fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY step toward fixing Windows path validation root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html
QUERY Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-filesystem-server-windows-access-denied-case-sensitivity.html

PIT mcp-github-remote-oauth-dcr-unsupported-use-pat
TITLE Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.md
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_FIRST Create a fine-grained GitHub Personal Access Token with the scopes you need.
QUERY Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication (PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY Claude Code cannot connect to GitHubs remote MCP server using OAuth authentication (PAT via GITHUB_PERSONAL_ACCESS_TOKEN is the confirmed workaround) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY how to fix Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html
QUERY claude-code oauth fails support dynamic client registration pat -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-github-remote-oauth-dcr-unsupported-use-pat.html

PIT mcp-inspector-docker-connection-refused-host-env
TITLE MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.md
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_FIRST Pass HOST and ALLOWED_ORIGINS to the container run command.
QUERY Docker container connection refused HOST + ALLOWED_ORIGINS workaround -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY how to fix MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html
QUERY mcp-inspector refuses connections unless host allowed origins set -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-docker-connection-refused-host-env.html

PIT mcp-inspector-release-regression-pin-version
TITLE MCP Inspector breaks after an upgrade; pin a known-good version
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.md
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_FIRST 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.
QUERY sh: mcp-inspector: command not found after upgrading to v0.10.0 downgrade to 0.9.0 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY sh: mcp-inspector: command not found after upgrading to v0.10.0 (downgrade to 0.9.0) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY Controller is already closed on fastmcp Streamable HTTP downgrade to 0.16.7; fixed in 0.17.5 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY Controller is already closed on fastmcp Streamable HTTP (downgrade to 0.16.7; fixed in 0.17.5) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY Controller is already closed on fastmcp Streamable HTTP (downgrade to 0.16.7; fixed in 0.17.5) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY MCP Inspector breaks after an upgrade; pin a known-good version -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html
QUERY MCP Inspector breaks after an upgrade; pin a known-good version fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-inspector-release-regression-pin-version.html

PIT 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
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.md
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_FIRST Clear the npm/npx cache and relaunch.
QUERY comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY comment confirming a corrupted npx cache from network errors caused the server to crash; clearing it fixed startup root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY Client closed / -32001 Request timed out around npx MCP startup -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY Client closed / -32001 Request timed out around npx MCP startup fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY Client closed / -32001 Request timed out around npx MCP startup root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY A corrupted or cold npx cache makes an MCP server fail to start or time out -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html
QUERY A corrupted or cold npx cache makes an MCP server fail to start or time out fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-npx-cache-corrupted-server-fails-to-start.html

PIT mcp-puppeteer-screenshots-in-memory-only
TITLE Puppeteer MCP screenshots live in memory only; there is no file on disk to find
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.md
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_FIRST Retrieve the screenshot via the MCP resource the server exposes, not from a file path.
QUERY Puppeteer MCP Server Missing Screenshots -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY Puppeteer MCP Server Missing Screenshots fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY Puppeteer MCP Server Missing Screenshots root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY Puppeteer MCP screenshots live in memory only; there is no file on disk to find -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY Puppeteer MCP screenshots live in memory only; there is no file on disk to find fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY Puppeteer MCP screenshots live in memory only; there is no file on disk to find root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY how to fix Puppeteer MCP screenshots live in memory only; there is no file on disk to find -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html
QUERY mcp-server live memory there no file disk find -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-puppeteer-screenshots-in-memory-only.html

PIT mcp-reference-server-archived-unmaintained
TITLE Several official reference MCP servers are archived; their bugs will not be fixed
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.md
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_FIRST Before debugging a reference server, check whether it is in modelcontextprotocol/servers-archived or flagged deprecated in the main README.
QUERY server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY server-postgres multi-instance issue closed; maintainer notes the server moved to servers-archived root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY maintainer deprecation notice that server-github development moved to github/github-mcp-server -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY maintainer deprecation notice that server-github development moved to github/github-mcp-server fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY maintainer deprecation notice that server-github development moved to github/github-mcp-server root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY Several official reference MCP servers are archived; their bugs will not be fixed -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html
QUERY Several official reference MCP servers are archived; their bugs will not be fixed fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reference-server-archived-unmaintained.html

PIT mcp-reverse-proxy-buffers-sse-connection-fails
TITLE A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.md
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_FIRST Disable response buffering for the MCP endpoint at the proxy.
QUERY Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY Claude Desktop custom MCP connection failure; confirmed root cause is Cloudflare Tunnel buffering SSE despite successful OAuth/initialize root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY how to fix A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html
QUERY claude-desktop breaks remote mcp after oauth initialize succeed -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-reverse-proxy-buffers-sse-connection-fails.html

PIT mcp-server-memory-ignores-memory-file-path-env
TITLE server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.md
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_FIRST Pin @modelcontextprotocol/server-memory@latest in the config to get the build that honors the env var (fix shipped in release 2025.4.25).
QUERY Environment variables not respected in @modelcontextprotocol/server-memory package -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY Environment variables not respected in @modelcontextprotocol/server-memory package fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY Environment variables not respected in @modelcontextprotocol/server-memory package root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY how to fix server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html
QUERY claude-desktop ignores file path npm build lagged source -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-server-memory-ignores-memory-file-path-env.html

PIT mcp-sse-received-request-before-initialization
TITLE SSE MCP server: Received request before initialization was complete
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.md
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_FIRST If a gateway/proxy is in front, use a spec-compliant one: switching supergateway -> mcp-proxy resolves the double-initialize case.
QUERY MCP SSE Server: Received request before initialization was complete comment confirms supergateway double-initialize; mcp-proxy works -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY MCP SSE Server: Received request before initialization was complete (comment confirms supergateway double-initialize; mcp-proxy works) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY SSE MCP server: Received request before initialization was complete -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY SSE MCP server: Received request before initialization was complete fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY SSE MCP server: Received request before initialization was complete root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY how to fix SSE MCP server: Received request before initialization was complete -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html
QUERY mcp-server mcp server received request initialization was complete -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-received-request-before-initialization.html

PIT mcp-sse-session-lost-multi-worker
TITLE MCP SSE session lost across workers/pods: Could not find session for ID (404)
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.md
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_FIRST Preferred: run stateless with Streamable HTTP so no per-connection in-memory session is required.
QUERY MCP Server Session Lost in Multi-Worker Environment comments confirm stateless_http=True and ingress sticky-hash fixes -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY MCP Server Session Lost in Multi-Worker Environment (comments confirm stateless_http=True and ingress sticky-hash fixes) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY MCP Server Session Lost in Multi-Worker Environment (comments confirm stateless_http=True and ingress sticky-hash fixes) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY MCP SSE session lost across workers/pods: Could not find session for ID 404 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY MCP SSE session lost across workers/pods: Could not find session for ID (404) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY MCP SSE session lost across workers/pods: Could not find session for ID (404) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY how to fix MCP SSE session lost across workers/pods: Could not find session for ID 404 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html
QUERY mcp-server lost across workers pods find id 404 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-sse-session-lost-multi-worker.html

PIT mcp-stateless-streamable-http-closedresourceerror
TITLE Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.md
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_FIRST Pin a known-good SDK version; users reported 1.11.0 working where 1.12.0 failed.
QUERY _handle_stateless_request ClosedResourceError reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY _handle_stateless_request ClosedResourceError (reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY _handle_stateless_request ClosedResourceError (reports 1.11.0 works, 1.12.0 fails; also FastMCP 2.10/2.13) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY how to fix Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html
QUERY mcp-server server throws anyio closedresourceerror some sdk versions -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stateless-streamable-http-closedresourceerror.html

PIT mcp-stdio-server-exits-shell-path-not-inherited
TITLE MCP stdio server exits immediately because the GUI client does not inherit your shell PATH
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.md
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_FIRST Confirm the failure is launch-environment, not a broken server: it runs in your terminal but fails when the client launches it.
QUERY MCP Servers Dont Work with NVM -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY MCP Servers Dont Work with NVM fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY MCP Servers Dont Work with NVM root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY npx-for-claude wrapper workaround 66 reactions -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY npx-for-claude wrapper workaround (66 reactions) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY npx-for-claude wrapper workaround (66 reactions) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY Server transport closed unexpectedly, process exiting early write EPIPE -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html
QUERY Server transport closed unexpectedly, process exiting early (write EPIPE) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-server-exits-shell-path-not-inherited.html

PIT mcp-stdio-stdout-logging-breaks-protocol
TITLE Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.md
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_FIRST Remove or redirect all stdout writes in the server; use stderr.
QUERY SyntaxError in stdio deserializeMessage a console.log in the server triggers it -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY SyntaxError in stdio deserializeMessage (a console.log in the server triggers it) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY SyntaxError in stdio deserializeMessage (a console.log in the server triggers it) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY how to fix Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html
QUERY mcp-server stdio mcp server corrupts json rpc stream -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-stdio-stdout-logging-breaks-protocol.html

PIT mcp-streamable-http-client-no-oauth-on-401
TITLE Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.md
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_FIRST Upgrade to a client/Inspector/SDK version where Streamable HTTP triggers OAuth on 401 (resolved in a released Inspector version).
QUERY When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 resolved in a released Inspector version -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 (resolved in a released Inspector version) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY When using Streamable HTTP transport, the oauth flow is not triggered when the server returns 401 (resolved in a released Inspector version) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY how to fix Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html
QUERY mcp-inspector client hangs 401 instead starting oauth flow -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-streamable-http-client-no-oauth-on-401.html

PIT mcp-time-server-invalid-local-timezone
TITLE mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.md
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_FIRST Pass an explicit IANA timezone with --local-timezone.
QUERY Time server fails under EDT timezone use --local-timezone with an IANA name -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY Time server fails under EDT timezone (use --local-timezone with an IANA name) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY Time server fails under EDT timezone (use --local-timezone with an IANA name) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY how to fix mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html
QUERY mcp-server local timezone abbreviation like edt pdt cest -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-time-server-invalid-local-timezone.html

PIT mcp-ts-client-default-60s-request-timeout
TITLE MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.md
PROBLEM McpError: MCP error -32001: Request timed out with data: { timeout: 60000 }
ROOT_CAUSE The default per-request timeout is 60000 ms.
FIX_FIRST Pass request options as the third argument to callTool with a larger timeout and resetTimeoutOnProgress: true.
QUERY mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY mcp client times out after 60 seconds (ignoring timeout option); comments confirm callTool request options and resetTimeoutOnProgress root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY how to fix MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html
QUERY mcp-server after 60s 32001 unless you reset progress -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-client-default-60s-request-timeout.html

PIT mcp-ts-sdk-commonjs-esm-pkce-challenge
TITLE MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge)
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.md
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_FIRST Upgrade @modelcontextprotocol/sdk to a version that lazily import()s pkce-challenge.
QUERY @modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency pkce-challenge -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY @modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY @modelcontextprotocol/sdk fails in CommonJS projects due to incompatible ESM-only dependency (pkce-challenge) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM pkce-challenge -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY how to fix MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM pkce-challenge -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html
QUERY mcp-server commonjs projects err require esm pkce challenge -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-commonjs-esm-pkce-challenge.html

PIT mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror
TITLE MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation)
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.md
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_FIRST On Cloudflare, use the McpAgent integration that added elicitation support; call elicitation on the McpAgent class, not mcpServer.server.
QUERY Elicitation feature fails on Cloudflare Workers due to AJV code generation EvalError -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY Elicitation feature fails on Cloudflare Workers due to AJV code generation (EvalError) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY MCP TS SDK validation fails on Cloudflare Workers with EvalError AJV code generation -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY how to fix MCP TS SDK validation fails on Cloudflare Workers with EvalError AJV code generation -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html
QUERY mcp-server fails cloudflare workers evalerror ajv code generation -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-edge-runtime-ajv-codegen-evalerror.html

PIT mcp-ts-sdk-type-instantiation-excessively-deep
TITLE MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.md
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_FIRST Ensure a single Zod version is installed; duplicates are a common trigger.
QUERY Type instantiation is excessively deep when importing ToolCallback Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY Type instantiation is excessively deep when importing ToolCallback (Zod author recommends single Zod version + modern moduleResolution; fixed in Zod 4.1.6) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY how to fix MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html
QUERY mcp-server type instantiation excessively deep ts2589 freezes ide -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-type-instantiation-excessively-deep.html

PIT mcp-ts-sdk-zod-v4-incompatible
TITLE MCP TypeScript SDK breaks with Zod v4: w._parse is not a function
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.md
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_FIRST Quick unblock: pin Zod v3 and ensure a single Zod version resolves.
QUERY MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY MCP TypeScript SDK breaks with Zod v4: w._parse is not a function -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY MCP TypeScript SDK breaks with Zod v4: w._parse is not a function fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY MCP TypeScript SDK breaks with Zod v4: w._parse is not a function root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY how to fix MCP TypeScript SDK breaks with Zod v4: w._parse is not a function -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html
QUERY mcp-server typescript sdk breaks zod v4 parse function -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-ts-sdk-zod-v4-incompatible.html

PIT mcp-windows-npx-requires-cmd-c-wrapper
TITLE On Windows an MCP server launched with npx needs a cmd /c wrapper
URL https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.md
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_FIRST Launch through cmd: set command to 'cmd' and args to ['/c','npx','-y','<package>', ...].
QUERY Windows npx launch failure with garbled 'not recognized' error -32000 -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY Windows npx launch failure with garbled 'not recognized' error (-32000) fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY Windows npx launch failure with garbled 'not recognized' error (-32000) root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY comment noting Windows/WSL needs 'cmd /c' before 'npx -y' and matching npm versions root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY On Windows an MCP server launched with npx needs a cmd /c wrapper -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html
QUERY On Windows an MCP server launched with npx needs a cmd /c wrapper fix -> https://laozhangzzz.github.io/agent-pitbook/pits/mcp-windows-npx-requires-cmd-c-wrapper.html

PIT portaudio-stream-close-blocks-hotkey-callback-thread
TITLE PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener
URL https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.md
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_FIRST Move recorder.stop() (the PortAudio stream.stop()/close() calls) AND all downstream processing off the pynput key-release callback thread into a background thread.
QUERY PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener fix -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY how to fix PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY portaudio close hotkey callback thread freeze global listener -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY portaudio close hotkey callback thread freeze global listener fix -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY freeze global listener stream stop close hotkey callback thread portaudio -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html
QUERY freeze global listener stream stop close hotkey callback thread portaudio fix -> https://laozhangzzz.github.io/agent-pitbook/pits/portaudio-stream-close-blocks-hotkey-callback-thread.html

PIT pynput-mixed-cjk-ascii-type-out-of-order-macos
TITLE pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste
URL https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.md
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_FIRST Switch text injection from per-character keyboard.type() to clipboard paste: copy the full string via pbcopy, then simulate Cmd+V.
QUERY pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste fix -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY how to fix pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY pynput mixed chinese english text macos clipboard paste -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY pynput mixed chinese english text macos clipboard paste fix -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY macos clipboard paste type scrambles mixed chinese english text pynput -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html
QUERY macos clipboard paste type scrambles mixed chinese english text pynput fix -> https://laozhangzzz.github.io/agent-pitbook/pits/pynput-mixed-cjk-ascii-type-out-of-order-macos.html

PIT uv-cache-outside-workspace-sandbox
TITLE uv fails in a managed workspace because cache or Python install paths are outside writable roots
URL https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
MARKDOWN https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.md
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_FIRST Set UV_CACHE_DIR to a workspace-local directory.
QUERY uv fails in a managed workspace because cache or Python install paths are outside writable roots -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY uv fails in a managed workspace because cache or Python install paths are outside writable roots fix -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY uv fails in a managed workspace because cache or Python install paths are outside writable roots root cause -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY how to fix uv fails in a managed workspace because cache or Python install paths are outside writable roots -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY codex workspace cache python install paths writable roots -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY codex workspace cache python install paths writable roots fix -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY paths writable roots fails managed workspace cache python install codex -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html
QUERY paths writable roots fails managed workspace cache python install codex fix -> https://laozhangzzz.github.io/agent-pitbook/pits/uv-cache-outside-workspace-sandbox.html