HostGate MCP

A Windows-first local capability control plane for MCP clients.

HostGate MCP gives an MCP client explicitly authorized access to selected local files and trusted command-line programs, with a desktop Control Center for policy, audit, rollback, diagnostics, and service lifecycle management.

The execution model is intentionally narrower than a general-purpose terminal: top-level cmd.exe, Windows PowerShell, and pwsh are not exposed as trusted execution tools. Allowed executables are resolved to fixed paths and launched directly.

Why HostGate exists

Reading local files through MCP is straightforward. Safely exposing write and process execution capabilities to a remote AI client is harder.

HostGate focuses on that control plane:

• explicit read / write / deny roots;
• transactional policy edits with diff review and rollback;
• permissions hot reload without restarting the MCP service;
• trusted executable allowlist with exact-path resolution;
• audited direct-process execution without a general-purpose shell;
• Windows Job Object process-tree containment;
• local audit history, configuration revisions, policy simulation, and diagnostics;
• a bilingual Windows Control Center (zh-CN / en-US);
• Scheduled Task lifecycle management;
• local stdio and OAuth-protected Streamable HTTP modes;
• PyInstaller onedir and portable onefile Control Center builds.

Security model

MCP client
    |
    | OAuth / stdio
    v
HostGate MCP
    |
    +-- Filesystem policy
    |     read roots
    |     write roots
    |     deny paths
    |
    +-- Direct execution policy
    |     trusted executable allowlist
    |     exact path resolution
    |     no general-purpose shell
    |     stdin disabled / bounded output
    |     Windows Job Object lifetime
    |
    +-- Control plane
          GUI / audit / revisions
          diagnostics / rollback

Important boundary

HostGate MCP is not an operating-system filesystem sandbox.

The filesystem policy controls HostGate's own file tools and the working directory accepted by exec_command. Once an authorized executable starts, that program and its descendants run with the OS privileges of the MCP service account and may access resources that account can access.

The executable allowlist constrains the top-level process. It does not sandbox descendants spawned by an authorized program.

Read SECURITY.md and docs/THREAT_MODEL.md before exposing the service beyond localhost.

Control Center

The Windows Control Center provides six pages:

• Service — status, PID, Scheduled Task start/stop/restart.
• Permissions — browse and manage read/write/deny roots.
• Execution — manage trusted CLI programs.
• Policy — simulate effective permissions and restore configuration revisions.
• Diagnostics — validate service/config/audit/revision state and export a redacted report.
• Audit — review recent file mutation and process execution events.

Policy changes use a transaction flow rather than editing TOML directly:

candidate
  -> validate
  -> review diff
  -> stale SHA256 check
  -> save previous revision
  -> atomic replace
  -> hot reload or controlled restart
  -> health check / rollback

Safe public defaults

The repository starts fail-closed:

• no read roots;
• no write roots;
• no user-defined deny paths (control-plane paths are denied automatically);
• only the Windows where.exe utility is trusted initially;
• OAuth URLs point to 127.0.0.1:8000;
• no real password hash, token database, audit data, or user policy is included.

Grant only the directories and executables you actually need from the Control Center.

Installation

Requirements:

• Windows 10/11;
• Python 3.10+;
• uv recommended.

Core server + GUI installation:

cd C:\path\to\hostgate-mcp
uv sync --no-dev
Copy-Item config\secrets.example.toml config\secrets.toml

The default installation includes filesystem/text/CSV/mutation/exec tools, OAuth HTTP support, and the Control Center. Format-specific readers are optional:

uv sync --extra excel      # Excel tools
uv sync --extra pdf        # PDF tools
uv sync --extra image      # image tools
uv sync --extra pytorch    # PyTorch checkpoint tools
uv sync --extra all        # all optional tool families

For development and the complete test suite:

uv sync --all-extras
.venv\Scripts\python.exe -m pytest -q

Set a real Argon2id owner password hash in config\secrets.toml, then configure roots and trusted executables before exposing the HTTP service.

Run the Control Center:

scripts\start_control_center.ps1

Install the Windows Scheduled Task when you are ready to run HostGate at logon:

scripts\install_server_task.ps1

Windows Control Center builds

Recommended onedir build:

scripts\build_control_center.ps1

Portable onefile build:

scripts\build_control_center.ps1 -OneFile

Build artifacts are intentionally excluded from source control.

Optional tool families

With every optional extra installed, HostGate exposes the full reader set developed for the private 1.4 line, including Excel, PDF, image, and PyTorch inspection tools. Without an extra, that tool family is simply not registered; the rest of the MCP server remains usable.

This keeps the default install focused on the RWX/control-plane use case instead of forcing every user to install large scientific dependencies such as PyTorch.

Project status

Current public-preparation version: 1.4.0rc1.

The public repository is created from a clean, history-free export of the tested private development line. Private Git history, production policy, OAuth state, logs, secrets, and build output are intentionally excluded.

Non-goals

HostGate is not trying to become:

• a full terminal emulator;
• a shell orchestration framework;
• an MCP marketplace or router;
• a cross-platform coding-agent replacement;
• a complete OS sandbox.

New capabilities should be added only when they solve a demonstrated operational or security problem.

Documentation

• SECURITY.md — security boundaries and vulnerability reporting.
• docs/THREAT_MODEL.md — assumptions, protected assets, and out-of-scope guarantees.
• docs/control_center.md — Control Center architecture and policy transactions.
• docs/architecture.md — server architecture.
• docs/tools.md — MCP tool reference.
• CHANGELOG.md — release history.

License

Licensed under the Apache License 2.0. See NOTICE for attribution information.