> ## Documentation Index
> Fetch the complete documentation index at: https://coding-1afcb9be.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose protocol, command, sandbox, permission, and environment issues.

# 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:

```bash theme={null}
curl http://127.0.0.1:8000/mcp
```

The direct CLI default is `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:

```text theme={null}
Authorization: Bearer <token>
```

For OAuth mode, confirm `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:

```bash theme={null}
coding-tools-mcp --host 0.0.0.0 --auth-token "$CODING_TOOLS_MCP_AUTH_TOKEN"
```

Use `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:

```bash theme={null}
coding-tools-mcp --tool-profile full
```

`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

In `safe` 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:

```bash theme={null}
coding-tools-mcp --permission-mode trusted
```

Use `--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:

```bash theme={null}
coding-tools-mcp --shell-env-inherit core
```

Then inspect the command environment with `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:

```bash theme={null}
coding-tools-mcp --workspace /path/to/workspace
```

Use `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

Use `apply_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 returned `session_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.

## Landlock warning

On Linux, the server uses Landlock filesystem confinement when available. If the host does not support it, command execution falls back to policy checks and reports a warning. Run untrusted workloads inside an external sandbox when Landlock is unavailable.