Skip to main content
Glama

MCP ToolHub

CI Python 3.12+

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.

MCP ToolHub trust-boundary architecture

Why it is different

Boundary

What ToolHub does

Human-only approval

The MCP client can submit and observe requests, but only the separate mcp-toolhub-admin process can approve or reject them.

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 trace_id.

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 serve

In 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 exactly

Windows 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 -> CONSUMED

Read 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

toolhub.ping

Check server reachability

Direct control; default SDK annotations

toolhub.audit_recent

Read recent sanitized audit metadata

Direct read-only

toolhub.capabilities

Discover Contract V1, mappings, and public limits

Direct read-only

toolhub.request_status

Observe effective request state

Direct read-only; never approves or consumes

filesystem.list_directory

List bounded workspace entries

Direct read-only

filesystem.read_file

Read a bounded UTF-8 workspace file and hash

Direct read-only

git.status

Inspect repository status

Direct read-only

git.diff

Inspect staged or unstaged diff

Direct read-only

filesystem.write_file

Validate and submit an exact file write

Approval submission; does not write

filesystem.write_file_approved

Resume the stored write by request ID

Approval-gated, single-use execution

filesystem.apply_patch

Validate and submit a single-file patch

Approval submission; does not patch

filesystem.apply_patch_approved

Resume the stored patch by request ID

Approval-gated, single-use execution

shell.run

Run the one LOW intrinsic or submit an external command

Direct LOW intrinsic; external execution requires approval

shell.run_approved

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 tool

There 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 CONFLICT without 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 --check

The 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 tools
filesystem.apply_patchApply workspace file patch (approval required)A
Destructive

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 patchA
Destructive

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 directoryB
Read-only

List files and directories inside the ToolHub workspace.

Inputs: path. Returns: path, entries

filesystem.read_fileRead workspace fileB
Read-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)A
Destructive

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 writeA
Destructive

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 diffA
Read-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 statusA
Read-only

Read-only git status of the ToolHub workspace repository.

Inputs: no named parameters. Returns: raw, path, clean, branch, +1 more

shell.runRun workspace commandA
Destructive

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 commandA
Destructive

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 eventsA
Read-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 capabilitiesC
Read-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 statusA
Read-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

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      11
      Apache 2.0