MCP ToolHub
Provides read-only Git repository inspection with status and diff tools, and supports administrator-approved Git shell commands for broader Git operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP ToolHub Show me the git status and current diff in the workspace."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP ToolHub
MCP ToolHub is a local, stdio-only Model Context Protocol (MCP) execution gateway for AI agents. It lets an agent inspect a bounded workspace and Git repository directly, while routing file mutations and every external command through an immutable, expiring, single-use request that only a human can approve.
It is deliberately small in surface area: 14 production tools, Contract V1 structured outcomes, no network listener, and no MCP endpoint for approval. The interesting work is at the execution boundary—turning an untrusted tool request into a bounded, reviewable, replay-resistant local action.
Why it is different
Boundary | What ToolHub does |
Human-only approval | The MCP client can submit and observe requests, but only the separate |
Immutable execution snapshots | Approved writes, patches, and commands resume from protected state, expire, and are consumed exactly once. |
Confined and observable execution | Workspace paths are bounded; subprocess output, runtime, and audit reads are capped; lifecycle events share a |
See it in 60 seconds
https://github.com/user-attachments/assets/8cab7be6-e43f-40a9-b6c6-ea7fae61acab
It lists exactly 14 tools, reads a file, pauses a write at
APPROVAL_REQUIRED, requires approval in the separate trusted admin process,
resumes execution, consumes the approval exactly once, and rejects replay.
For a reproducible walkthrough, see the demo guide.
Related MCP server: agent-bridge-mcp
Quick start
Requires Python 3.12 or newer and uv.
Install the two commands from a source checkout:
uv tool install .Point ToolHub at an existing absolute workspace. A separate state root is optional but useful when demonstrating the trust boundary:
export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub-example
mcp-toolhub serveIn normal use, an MCP client starts mcp-toolhub serve as its stdio child
process. The server writes protocol messages only to stdout and opens no
HTTP/SSE listener.
For human review, open a separate terminal with the same two environment variables:
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
# inspect the snapshot, then type APPROVE exactlyWindows PowerShell setup, MCP client JSON, default state locations, maintenance, and troubleshooting are in Operations.
For development, uv sync --all-groups creates the project environment and
editable install with the locked test and lint dependencies. This is distinct
from the normal uv tool install . source installation.
Architecture at a glance
The MCP client is untrusted. It receives direct access only to bounded inspection and control tools. An initial mutation or external-command call validates its input and stores the exact proposed action in trusted state outside the workspace; it does not perform that action.
The administrator reviews the protected snapshot out of band. After approval,
the client can invoke only the matching resume tool with the request_id.
ToolHub atomically consumes the approval before executing the stored action,
preventing replay.
initial tool -> APPROVAL_REQUIRED -> PENDING
-> human approve/reject
-> APPROVED / REJECTED / EXPIRED
-> resume tool -> execution result -> CONSUMEDRead the architecture and threat model for trust boundaries and guarantees, and the approval lifecycle for Contract V1 client logic.
Production tool surface
The production server exposes exactly 14 MCP tools:
Tool | Purpose | Execution class |
| Check server reachability | Direct control; default SDK annotations |
| Read recent sanitized audit metadata | Direct read-only |
| Discover Contract V1, mappings, and public limits | Direct read-only |
| Observe effective request state | Direct read-only; never approves or consumes |
| List bounded workspace entries | Direct read-only |
| Read a bounded UTF-8 workspace file and hash | Direct read-only |
| Inspect repository status | Direct read-only |
| Inspect staged or unstaged diff | Direct read-only |
| Validate and submit an exact file write | Approval submission; does not write |
| Resume the stored write by request ID | Approval-gated, single-use execution |
| Validate and submit a single-file patch | Approval submission; does not patch |
| Resume the stored patch by request ID | Approval-gated, single-use execution |
| Run the one LOW intrinsic or submit an external command | Direct LOW intrinsic; external execution requires approval |
| Resume the stored external command by request ID | Approval-gated, single-use execution |
The three pairs follow the same protocol:
initial tool -> APPROVAL_REQUIRED -> human approval -> resume toolThere is no toolhub.approve, toolhub.reject, administration namespace, or
other MCP path to a human decision.
Contract V1
Approval-gated results use MCP structuredContent as the authoritative
machine-readable response. Clients should branch on outcome, approval,
and error rather than parsing display text.
Every lifecycle carries a trace_id. Approval handles contain the
request_id, current status, expiry, and server-selected resume_tool.
Expected domain states—including pending, rejected, expired, consumed,
conflict, refusal, timeout, and nonzero command exit—are structured outcomes.
Schema validation failures and unexpected internal failures remain MCP/tool
errors.
Contract V1 is locked by a readable compatibility fixture and tests. Package
version 0.1.0 and contract version 1.0 are independent.
Security model
All workspace API paths are relative, canonically confined, and checked for portable traversal; mutation paths also reject symlink components.
File writes and patches require out-of-band human approval and execute only their protected immutable snapshots.
Approval requests are atomic, expiring, workspace-bound, and single-use.
Optional expected hashes provide optimistic concurrency checks for mutations; mismatches return
CONFLICTwithout publishing a write.External commands use structured arguments,
shell=False, a sanitized approval-bound environment, and a revalidated primary-executable snapshot.External commands and fixed Git helpers run inside OS-backed process-tree lifetime containment with bounded timeouts and output capture.
Read-only Git inspection refuses risky helper paths such as applicable executable filters, external diff/textconv, pagers, and submodules.
Trusted state is bound to one canonical workspace and must live outside that workspace.
Audit events are bounded and redact recognizable secret arguments; they do not store raw stdout or stderr.
These controls bound ToolHub itself and reduce confused-deputy risk; they do not turn approved programs into safely sandboxed code. See Architecture for precise assumptions and limitations.
Non-goals
Not a cloud or remote MCP gateway
Not an authentication, multi-user, or RBAC platform
Not a general operating-system sandbox or container
No autonomous or agent-driven approval
No HTTP, SSE, or other network transport
No claim that approved commands are filesystem- or network-isolated
Documentation
Development and verification
uv sync --all-groups
uv lock --check
uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --checkThe installed-wheel smoke driver validates the built artifact outside the checkout:
uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .On Windows, use a temporary path such as
"$env:TEMP\mcp-toolhub-wheel-env" for --venv. CI runs the complete gate and
wheel smoke test on Ubuntu and Windows with Python 3.12 and 3.13.
Available Tools
14 toolsfilesystem.apply_patchApply workspace file patch (approval required)ADestructive
Create a PENDING approval request for a narrowly-scoped patch.
The patch may modify only the requested file, and is applied only after out-of-band approval via filesystem.apply_patch_approved.
Inputs: path (required), patch (required), expected_hash. Returns: path, error, changed, message, +12 more
filesystem.apply_patch_approvedExecute an approved file patchADestructive
Execute exactly the patch stored in an APPROVED request.
Takes only a request_id; the stored snapshot is used. Single-use.
Inputs: request_id (required). Returns: path, error, changed, message, +12 more
filesystem.list_directoryList workspace directoryBRead-only
List files and directories inside the ToolHub workspace.
Inputs: path. Returns: path, entries
filesystem.read_fileRead workspace fileBRead-only
Read a UTF-8 text file inside the ToolHub workspace.
Inputs: path (required). Returns: path, size, sha256, content
filesystem.write_fileWrite workspace file (approval required)ADestructive
Create a PENDING approval request for writing a UTF-8 text file.
The write happens only after a trusted administrator approves the request out-of-band and filesystem.write_file_approved executes the stored snapshot.
Inputs: path (required), content (required), expected_hash, create_parents. Returns: path, error, created, message, +9 more
filesystem.write_file_approvedExecute an approved file writeADestructive
Execute exactly the file write stored in an APPROVED request.
Takes only a request_id; the path/content/hash snapshot captured at request time is used. Single-use.
Inputs: request_id (required). Returns: path, error, created, message, +9 more
git.diffShow git diffARead-only
Read-only git diff. Never modifies repository state.
Args: path: Optional repository-relative path to filter the diff. staged: Show staged changes (git diff --cached) instead of unstaged ones.
Inputs: path, staged. Returns: raw, path, binary, staged, +2 more
git.statusShow git working tree statusARead-only
Read-only git status of the ToolHub workspace repository.
Inputs: no named parameters. Returns: raw, path, clean, branch, +1 more
shell.runRun workspace commandADestructive
Run a structured subprocess inside the ToolHub workspace.
Only LOW-risk commands execute automatically. MEDIUM/HIGH commands create a PENDING approval request that a trusted administrator must approve out-of-band before it can be run via shell.run_approved.
Inputs: program (required), cwd, args, timeout_seconds. Returns: cwd, args, risk, error, +13 more
shell.run_approvedRun an approved commandADestructive
Execute a previously-APPROVED command exactly as stored.
Takes only a request_id; the program, args, and cwd are always the originals captured when the request was created. Approvals are single-use, so a request cannot be replayed.
Inputs: request_id (required). Returns: cwd, args, risk, error, +13 more
toolhub.audit_recentRecent audit eventsARead-only
Return the most recent sanitized audit events (max 100).
Read-only: returns bounded metadata summaries. Event contents are already sanitized at write time; no raw stdout/stderr or secrets are included.
Inputs: limit. Returns: count, events
toolhub.capabilitiesShow ToolHub capabilitiesCRead-only
Return the versioned public ToolHub execution contract.
Inputs: no named parameters. Returns: limits, transport, approval_model, package_version, +2 more
toolhub.pingB
Check whether MCP ToolHub is running correctly.
Inputs: message. Returns: object
toolhub.request_statusShow approval request statusARead-only
Observe an approval request without approving, rejecting, or consuming it.
Inputs: request_id (required). Returns: error, outcome, approval, trace_id, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Tools are cleanly partitioned into namespaces (filesystem, shell, git, toolhub) and actions. The approval-request tools and their _approved counterparts have clearly distinct purposes, and descriptions explicitly explain the two-step approval flow, so an agent can reliably choose the right tool.
All tool names follow a consistent namespace.action pattern using dot separators and snake_case actions. The _approved suffix is applied uniformly to the three post-approval execution tools, making the naming predictable throughout.
The 14 tools are well-scoped for a secured execution hub: read/list, write/patch requests, shell requests, their approved counterparts, read-only git, and lightweight diagnostics/audit. No tool appears redundant, and the count stays within a reasonable range.
Core lifecycle operations for workspace inspection, file reading, controlled writes/patches, shell execution, git status/diff, and audit/request observation are covered. Minor gaps exist—no filesystem delete/move, no direct git history/log tools, and no pending-request listing—but agents can largely work around these via shell.run or request_status.
Maintenance
Related MCP Connectors
Runtime permission, approval, and audit layer for AI agent tool execution.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.1-
- AlicenseNot gradedqualityCmaintenanceEnables controlled delegation of tasks to local coding-agent CLIs and the Manus API, with strict sandboxing, approval tracking, and remote-egress safeguards.17 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.8 npm6MIT
- AlicenseAqualityBmaintenanceEnables coding agents to safely inspect and modify project files within explicitly allowed workspace roots, with controls for file operations, git status/diff, and optionally allowlisted command execution.11Apache 2.0