Troubleshooting
Use this page when a client cannot connect, a tool is missing, or a command behaves differently from a normal shell.Client cannot connect
Check the transport first. For HTTP, verify the server is listening on the expected endpoint:127.0.0.1:8000. Some helper scripts or tunnel docs may use 8765, so confirm the actual --port, CODING_TOOLS_MCP_PORT, wrapper script, and client URL.
For stdio, make sure the client command includes --stdio and that no extra logging is written to stdout. JSON-RPC responses must stay on stdout; diagnostics should go to stderr.
HTTP returns unauthorized
If you configured--auth-token or CODING_TOOLS_MCP_AUTH_TOKEN, the client must send:
CODING_TOOLS_MCP_SERVER_URL matches the externally visible URL when the server is behind a proxy or tunnel.
Non-loopback HTTP refuses to start
The implementation rejects non-loopback binding without auth. Fix it by adding Bearer auth or OAuth:CODING_TOOLS_MCP_AUTH_MODE=noauth only when another trusted layer provides authentication and network isolation.
Tool is missing from tools/list
Check the active profile:
read-only hides mutating tools such as apply_patch, exec_command, write_stdin, kill_session, set_default_cwd, and request_permissions. view_image is disabled when CODING_TOOLS_MCP_ENABLE_VIEW_IMAGE=0.
Command is blocked
Insafe mode, the server blocks common risky command patterns. Typical diagnostics include network, shell expansion, inline script, sensitive environment, destructive command, long timeout, privileged executable, or generated/ignored write restrictions.
For normal local development commands that need package managers or shell features, restart with:
--allow-network only when the issue is specifically network-looking command detection.
Command cannot find an executable
exec_command inherits a controlled environment. Check what the server sees:
check_exec_environment and, if needed, pass explicit environment values through the tool call. Avoid passing secret-looking values in safe or trusted modes because they are filtered.
Path is rejected or file is not found
All direct file tools resolve paths against the configured workspace. Confirm the server was started with the intended root:get_default_cwd and set_default_cwd when relative command working directories do not point where the client expects.
read_file fails on encoding or binary content
read_file supports UTF-8 text. Binary-looking files and invalid UTF-8 are rejected. Use view_image for supported local images, or command tools for other binary inspection workflows when appropriate.
Patch fails
Useapply_patch with dry_run: true to validate before writing. Common causes are stale context, wrong workspace path, generated or ignored file policies, and patch text that is not in the expected format.
Long-running session issues
For commands that keep running, capture the returnedsession_id, poll with write_stdin using empty chars, send input with write_stdin, and terminate with kill_session. Output can be truncated by max_output_bytes and the session buffer size, so poll regularly for verbose commands.