Mathematic Inc.
← Repository indexResearch note 03 / 20
Agents & interfacesImplementation note

claude-tools-mcp

File and shell tools at an HTTP endpoint

Mathematic Inc.September 12, 20263 min read

Abstract

An MCP client may need to work on files and processes in a different execution environment. claude-tools-mcp offers a familiar file-and-shell tool surface through Streamable HTTP. It implements those operations in a Go server, so clients can share an execution endpoint without depending on one editor's built-in tool implementation. [1][2]

Source repository

1. The problem

A local stdio server normally starts as a child process of the client. That is a poor match when the working directory, installed commands, or long-running processes belong to a separate host or container. MCP's HTTP transport makes an independently hosted server possible, but a transport alone does not implement file editing or process management. [3]

The repository fills that operational gap with concrete read, write, exact-edit, glob, grep, and shell tools. The engineering rationale is portability of the tool surface across MCP clients. Its name describes the familiar operations it offers; it is a separate implementation, not a mechanism for inheriting Claude Code's permission system. [1][2]

2. The design

The server registers typed tools through the MCP Go SDK. Search delegates to ripgrep. Shell operations support timeouts and background execution, with separate operations for reading output, listing shells, and terminating a process. The file tools impose size and result limits and require absolute paths. [1][2]

The HTTP handler runs in stateless protocol mode, but the application still keeps file-modification tracking and background-shell state. A deployment that distributes requests between replicas therefore needs to account for which process owns a shell; protocol statelessness does not make a running process portable between hosts. [1][2]

3. Alternatives

The relevant distinction is the requirement each approach serves.

3.1 A local stdio MCP server

The constraint
In the standard stdio arrangement, the client launches the server process. Its filesystem and toolchain follow that launch environment. [3]
Our approach
The HTTP server runs independently, allowing the operator to choose the execution host or container. [1]
The tradeoff
A local stdio server avoids exposing a network service and is sufficient when the client and workspace belong on the same machine.

3.2 An SSH shell

The constraint
SSH gives a remote command session. A client needing distinct read, edit, search, and background-output operations must add its own structured adapter around that session.
Our approach
This server supplies those operations as MCP tools with defined inputs and result limits. [1][2]
The tradeoff
SSH already provides transport authentication and interactive administration. This server's entry point does not add an equivalent authentication layer. [2]

4. Boundaries & adoption

The checked entry point binds to localhost by default and configures HTTP timeouts and graceful shutdown. It does not install application authentication middleware. Absolute paths and file-size limits are not filesystem isolation. Network access must be controlled by the deployment, and the process should have only the host permissions its callers are meant to exercise. [2][3]

Choose it for a controlled execution environment where structured remote tools are useful. Use Earl when the intended interface is a restricted operation catalog; these two projects expose materially different levels of authority.

5. References

Sources reviewed September 12, 2026. Mathematic source links retain the reviewed revision.

  1. [1]
  2. [2]
  3. [3]