Troubleshooting

Protocol Version Errors

Send MCP-Protocol-Version on every HTTP request. A 2026-07-28 client sends MCP-Protocol-Version: 2026-07-28, repeating the version in its params._meta; a header that disagrees with the body, or is missing from such a request, returns 400 with -32020. A handshake client sends the version it negotiated at initialization, normally MCP-Protocol-Version: 2025-11-25, or 2025-06-18 for compatibility. A header naming a version this server does not know returns 400 with -32600 and lists the ones it does; a request with no header at all is read as 2025-11-25.

Asking to handshake with a version this server does not speak is no longer an error: initialize answers with the newest version it does speak. If a client seems to be on an older protocol than expected, read the protocolVersion in the InitializeResult rather than assuming the one that was requested.

SANDBOX_UNAVAILABLE

If exec_command returns a warning about Linux Landlock being unavailable, the command still ran under server-side policy checks, but without kernel filesystem confinement. This is expected on Windows, macOS, and Linux hosts without Landlock support. Put the server inside an external sandbox before running untrusted commands or untrusted project code.

If an older client or server reports SANDBOX_UNAVAILABLE as an error, upgrade to the current behavior or run on a Landlock-capable Linux kernel.

Command Hangs Or Times Out

If the result returns status: "running", poll with write_stdin using empty chars, or terminate with kill_command. Command deadlines still apply when the client stops polling.

Permission Elicitation Is Unsupported

If request_permissions returns ELICITATION_UNSUPPORTED, the MCP client cannot show approval prompts. For dependency downloads and local development, prefer --permission-mode trusted; it allows network-looking commands, shell expansion, and inline scripts while keeping secret filtering and destructive-command checks. For isolated containers or VMs, use --permission-mode dangerous to disable exec_command permission gates.

Missing Toolchain Environment

exec_command defaults to a core shell environment. If tools such as MSVC, CUDA, oneAPI, or Nix depend on variables from the parent terminal, start the server with:

CODING_TOOLS_MCP_SHELL_ENV_INHERIT=all coding-tools-mcp --workspace /path/to/repo

This still filters secret-looking and loader/startup variables unless --permission-mode dangerous is also enabled.

Exec Diagnostics

exec_command may include diagnostics with codes such as DEV_NULL_DENIED, DNS_RESOLUTION_FAILED, NETWORK_PERMISSION_REQUIRED, TMPDIR_NOT_WRITABLE, HOME_NOT_WRITABLE, COMMAND_TIMED_OUT, and OUTPUT_TRUNCATED. See troubleshooting-exec.md.

Trace Tool Calls

For local debugging:

CODING_TOOLS_MCP_TRACE=1 coding-tools-mcp --workspace /path/to/repo

Trace events are JSON lines on stderr. Arguments are redacted for secret-looking keys and values; stdout remains reserved for stdio JSON-RPC frames.

SWE-bench

If Docker or the swebench package is missing, the default scaffold should report PREFLIGHT_ONLY; an explicit evaluation attempt should report BLOCKED, not pass. See swe-bench.md.