Coding Tools MCP: a workspace-confined coding runtime for any MCP client

What Coding Tools MCP solves, and who it is aimed at

A chat client that can talk about code is not the same as one that can change it. Coding Tools MCP exists to close that gap: it is a model-neutral coding runtime served over the Model Context Protocol, exposing file reading and search, structured multi-file patches, command execution, interactive sessions and git through a single server that any MCP client can drive. The README names Claude Desktop, Claude Code, Codex, Cursor, Cline, VS Code, Windsurf, Gemini CLI, or an agent you build yourself.

The pitch is narrow and worth reading literally. The README says the project "turns a chat app into a coding agent", which means the target user is someone who already has a subscription to an MCP-capable client and does not want to buy another product to get repository access. The second audience is agent builders: the docs/embedding.md path is for people writing an agent loop against the Anthropic SDK or anything else, who would otherwise hand-roll file and exec tools and inherit the safety problems that come with them.

What the project is not: it is not an editor, not a language server, and not a code model. It ships no intelligence of its own. Everything it does is a tool call that some other model decided to make.

One workspace root, permission modes, and the tool catalog

The architecture is a single server process bound to one workspace root. The README states that absolute paths, `..` traversal and symlink escapes are rejected, and that permission modes gate network access, shell expansion, inline scripts and destructive commands. On Linux, Landlock adds kernel-level filesystem confinement according to docs/security-boundary.md. That is the whole safety model: confinement at the boundary rather than per-tool heuristics.

The registry holds 19 tools. The default `safe` and `trusted` modes advertise 18 of them; `dangerous` additionally advertises `request_permissions`, which the README describes as the only mode in which that tool can grant anything. The catalog splits into four groups. Files and search: `read_file`, `list_dir`, `list_files`, `search_text`, `apply_patch`, `apply_changes`, `view_image`. Execution: `exec_command`, `write_stdin`, `read_output`, `kill_command`, plus `request_permissions`. Git: `git_status`, `git_diff`, `git_log`, `git_show`, `git_blame`. Runtime: `server_info`, `check_exec_environment`.

The mutation primitives are `apply_patch` and `apply_changes`, and the README describes both as staged, baseline-checked, atomic across files, and rollback-capable. That combination matters more than the tool count. A patch that checks its baseline before applying will refuse rather than silently clobber a file the model read several turns ago.

Context discipline is a stated design goal rather than a side effect. The README claims results are summarized, paginated and capped by design, and reports that serialized tool-result bytes dropped 37% release-over-release on the deterministic dogfood workload with unchanged task completion. That is a self-reported figure from the project's own workload; treat it as a direction of travel, not an independently verified benchmark.

Interactive processes get first-class treatment. `exec_command` starts a REPL or debugger under a real PTY, `write_stdin` feeds it across turns, `read_output` pages long output, and `kill_command` cleans up, with deadline watchdogs and bounded buffers. Root `AGENTS.md` or `CLAUDE.md` files load automatically and come back in the `instructions` field of `initialize`.

Installing Coding Tools MCP and wiring it into a client

The server is Python 3.11 or newer from PyPI. The npm package is described as a thin launcher that starts it via `uv` or `pipx`, so the Node path is a convenience wrapper, not a second implementation. Pick whichever toolchain you already have:

uvx coding-tools-mcp --stdio --workspace /path/to/repo   # Python toolchain
npx coding-tools-mcp --stdio --workspace /path/to/repo   # Node toolchain

Both commands start the server on stdio with a single workspace root. The README says the client JSON is the same everywhere, so swap `uvx` for `npx` if you prefer Node:

{
  "mcpServers": {
    "coding-tools": {
      "command": "uvx",
      "args": ["coding-tools-mcp", "--stdio", "--workspace", "/path/to/repo"]
    }
  }
}

After adding that block to your client's MCP configuration and restarting it, the server should appear in the client's tool list. The README's suggested first task is to ask your client to "run the test suite and fix the first failure". A more cautious first call is `server_info`, which reports what the server thinks it is, or `check_exec_environment`, which tells you whether the shell and toolchain inside the workspace are what you expect.

If you would rather not install Python locally, the repository ships a Dockerfile and a docker-compose.yml. The README's sandbox recipe is:

docker build -t coding-tools-mcp-sandbox:local .
docker run --rm --init -it -p 8765:8765 -v "$PWD:/workspace" coding-tools-mcp-sandbox:local

The compose file pins the host side of the port mapping to loopback, reads `CODING_TOOLS_MCP_PORT` (default 8765) and `CODING_TOOLS_MCP_AUTH_TOKEN` (default `dev-token`), sets `CODING_TOOLS_MCP_PERMISSION_MODE` to `trusted`, and mounts the current directory at `/workspace`. That default token is a development placeholder; do not expose the port beyond loopback with it in place.

There is also a desktop client, installed as an optional extra:

python -m pip install "coding-tools-mcp[desktop]"
coding-tools-mcp-desktop

The README describes it as offering per-workspace profiles, server and tunnel start/stop, credential setup with clipboard helpers, and live health checks, in English and Simplified Chinese.

HTTP transport, tunnels, and what neither transport gives you

Dropping `--stdio` makes the server speak Streamable HTTP on `http://127.0.0.1:8765/mcp`. The README states that both protocol eras are served on either transport: MCP `2026-07-28` in full with `tools` as the only advertised capability, and the handshake era `2025-11-25` with `2025-06-18` compatibility. It also states that neither era has sessions. That last detail is easy to skim past. No sessions means no per-connection state to resume, so a client that assumes it can reconnect into an existing conversation state will not find one here.

Remote access is handled by binding to loopback and putting an authenticated HTTPS tunnel in front. The README's example uses the bundled Cloudflare tunnel script:

CODING_TOOLS_MCP_AUTH_MODE=bearer ./integrations/tunnels/tunnel.sh cloudflared /path/to/repo

Bearer tokens and OAuth 2.1 with PKCE, including RFC 7591 dynamic registration, are described as built in. The README also mentions `ngrok` and Microsoft Dev Tunnel as alternatives, and says ChatGPT and Grok connect through their connector settings the same way. The tunnel script path and the environment variable name above are copied from the README; the docs/remote-mcp.md file is where the project puts the rest.

A second remote option avoids running a server at all. The bundled Cloudflare Worker control plane under infra/cloudflare/sandbox-control exposes `start_coding_tools_sandbox` as an MCP tool: one call dispatches a GitHub Actions runner that boots the Docker sandbox and publishes it behind an authenticated Cloudflare Tunnel. That is a materially different operational shape from the tunnel script, and it is worth deciding which one you actually want before reading further.

Where Coding Tools MCP is the wrong choice

The confinement model is also the main limitation. One workspace root per server process means a task that spans two repositories needs two server entries and two sets of credentials, or a workspace root high enough in the tree that the confinement stops meaning much. The README does not describe a multi-root mode.

Permission modes are coarse. There are three named modes, and `request_permissions` is unavailable outside `dangerous`. If your threat model needs a capability that sits between `trusted` and `dangerous`, the documentation does not show one. The Docker image sets `CODING_TOOLS_MCP_PERMISSION_MODE=trusted` by default, which is a reasonable container default but not a substitute for deciding what the agent should be allowed to do.

The catalog is deliberately small at 19 entries. There is no refactoring tool, no package-manager abstraction, no test runner of its own. Everything beyond read, patch, exec and git has to be expressed as a shell command through `exec_command`, which puts the burden back on the model to get the command right. If you want a tool that understands your build system, this is not it.

Finally, the project depends on the MCP ecosystem being present in your client. If your editor or chat product does not speak MCP, or speaks it in a way that does not accept a `mcpServers` block, none of the above applies. The README's client list is the boundary of what the project claims to support, and it does not document a fallback for clients outside that list.

How it compares to Claude Code and to hand-rolled agent tools

The closest comparison is Claude Code, and the difference is architectural rather than feature-level. Claude Code is a coding agent with its own interface, its own session model and its own opinions about how you work. Coding Tools MCP is a runtime that other clients drive. If you already use Claude Code, adding this server gives Claude Code the same 18 tools it largely already has, which is redundant. If you use Claude Desktop, Cursor, Cline or a chat client of your own, the server is what turns that client into something that can act on a repository.

The second comparison is against writing your own tools. The docs/embedding.md path is explicitly for agent builders, and the argument in the README is that you inherit the whole safety boundary instead of reimplementing path validation, patch staging and output capping. That argument holds if you agree with the boundary as drawn. If your agent needs a different confinement model, or needs to operate outside a single root, adopting this server means adopting its constraints along with its tools.

The third comparison is the bundled Cloudflare Worker control plane against the local tunnel script. The tunnel script keeps the workspace on your machine and exposes it. The Worker dispatches a GitHub Actions runner that boots the Docker sandbox and publishes it. Same server, very different answers to where the code lives and who pays for the compute.

Maintenance, licence, and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-03. The most recent release is v0.3.0, published on 2026-08-13, alongside v0.3.0rc1 and v0.2.3 from the same day. The version in pyproject.toml is 0.3.0, which matches the release tag.

The project is Apache-2.0, declared in pyproject.toml as a file reference to LICENSE and classified as an OSI-approved Apache licence. Apache-2.0 includes an explicit patent grant and requires preservation of notices, which matters if you redistribute the server inside a product. The repository also carries a NOTICE file and a CITATION.cff. None of that is legal advice; read LICENSE and NOTICE yourself before shipping anything derived from it.

The upgrade surface is small in one direction and large in another. Runtime dependencies in pyproject.toml are just PyJWT, so the Python footprint is light. But the optional extras pull in more: the dev extra pins `mcp>=2.0`, mypy, PyYAML, ruff and typing_extensions, the desktop extra pins PySide6 and psutil, and the image extra pins Pillow. The desktop client is the heaviest thing here, and it is the part most likely to break on a Qt upgrade.

Compatibility risk concentrates in the protocol layer. The server advertises MCP `2026-07-28` in full plus `2025-11-25` with `2025-06-18` compatibility, and the dev extra notes that the official MCP SDK is the only client in the test suite the project did not write. If your client implements a different era, that is the first thing to test after upgrading. The Makefile exposes a `test-dual-era` target, which suggests the project treats era coverage as something to verify rather than assume.

Editorial conclusion

Adopt Coding Tools MCP if you already pay for an MCP-capable chat client and want repo access without a new product, or if you are building an agent loop and would rather speak MCP than hand-roll file and exec tools. Skip it if you need a GUI-first coding environment, if you cannot run a local Python 3.11+ process or Docker container, or if your workflow depends on a tool outside the 19-entry catalog. Before rolling it out, verify three things: that your client accepts the mcpServers JSON block, that --workspace points at the repository you actually intend to expose, and that the permission mode you start in is the one you want, since request_permissions only exists under dangerous.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. xyTom/coding-tools-mcp on GitHub