HostGate MCP

Un plano de control de capacidades local para clientes MCP, pensado primero para Windows.

HostGate MCP ofrece a un cliente MCP acceso explícitamente autorizado a archivos locales seleccionados y programas de línea de comandos de confianza, con un Centro de control de escritorio para la gestión de políticas, auditoría, reversión, diagnósticos y ciclo de vida del servicio.

El modelo de ejecución es intencionadamente más restringido que el de un terminal de propósito general: cmd.exe de nivel superior, Windows PowerShell y pwsh no se exponen como herramientas de ejecución de confianza. Los ejecutables permitidos se resuelven a rutas fijas y se lanzan directamente.

Por qué existe HostGate

Leer archivos locales a través de MCP es sencillo. Exponer de forma segura las capacidades de escritura y ejecución de procesos a un cliente de IA remoto es más difícil.

HostGate se centra en ese plano de control:

• raíces explícitas de lectura / escritura / denegación;

• ediciones transaccionales de políticas con revisión de diferencias (diff) y reversión;

• recarga en caliente de permisos sin reiniciar el servicio MCP;

• lista blanca de ejecutables de confianza con resolución de ruta exacta;

• ejecución directa de procesos auditada sin shell de propósito general;

• contención del árbol de procesos mediante Windows Job Object;

• historial de auditoría local, revisiones de configuración, simulación de políticas y diagnósticos;

• un Centro de control de Windows bilingüe (zh-CN / en-US);

• gestión del ciclo de vida de Scheduled Task;

• modos stdio local y Streamable HTTP protegido por OAuth;

• compilaciones del Centro de control con PyInstaller onedir y portátiles onefile.

Related MCP server: MCP Local Filesystem Server

Modelo de seguridad

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

Límite importante

HostGate MCP no es un sandbox de sistema de archivos del sistema operativo.

La política del sistema de archivos controla las herramientas de archivo propias de HostGate y el directorio de trabajo aceptado por exec_command. Una vez que se inicia un ejecutable autorizado, ese programa y sus procesos descendientes se ejecutan con los privilegios del sistema operativo de la cuenta de servicio de MCP y pueden acceder a los recursos a los que esa cuenta puede acceder.

La lista blanca de ejecutables limita el proceso de nivel superior. No aísla en sandbox los procesos descendientes generados por un programa autorizado.

Lea SECURITY.md y docs/THREAT_MODEL.md antes de exponer el servicio más allá de localhost.

Centro de control

El Centro de control de Windows proporciona seis páginas:

• Servicio — estado, PID, inicio/parada/reinicio de Scheduled Task.

• Permisos — explorar y gestionar raíces de lectura/escritura/denegación.

• Ejecución — gestionar programas CLI de confianza.

• Política — simular permisos efectivos y restaurar revisiones de configuración.

• Diagnósticos — validar el estado del servicio/configuración/auditoría/revisiones y exportar un informe depurado.

• Auditoría — revisar eventos recientes de mutación de archivos y ejecución de procesos.

Los cambios de política utilizan un flujo transaccional en lugar de editar TOML directamente:

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

Valores predeterminados públicos seguros

El repositorio comienza en modo fail-closed:

• sin raíces de lectura;

• sin raíces de escritura;

• sin rutas de denegación definidas por el usuario (las rutas del plano de control se deniegan automáticamente);

• solo la utilidad where.exe de Windows es de confianza inicialmente;

• las URL de OAuth apuntan a 127.0.0.1:8000;

• no se incluye ningún hash de contraseña real, base de datos de tokens, datos de auditoría ni política de usuario.

Conceda únicamente los directorios y ejecutables que realmente necesite desde el Centro de control.

Instalación

Requisitos:

• Windows 10/11;

• Python 3.10+;

• uv recomendado.

Instalación del servidor principal + GUI:

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

La instalación predeterminada incluye herramientas de sistema de archivos, texto, CSV, mutación y ejecución, soporte HTTP OAuth y el Centro de control. Los lectores específicos de formato son opcionales:

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

Para el desarrollo y la suite de pruebas completa:

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

Establezca un hash de contraseña de propietario Argon2id real en config\secrets.toml y configure las raíces y los ejecutables de confianza antes de exponer el servicio HTTP.

Ejecute el Centro de control:

scripts\start_control_center.ps1

Instale la Scheduled Task de Windows cuando esté listo para ejecutar HostGate al iniciar sesión:

scripts\install_server_task.ps1

Compilaciones del Centro de control de Windows

Compilación onedir recomendada:

scripts\build_control_center.ps1

Compilación portátil onefile:

scripts\build_control_center.ps1 -OneFile

Los artefactos de compilación se excluyen intencionadamente del control de versiones.

Familias de herramientas opcionales

Con cada complemento opcional instalado, HostGate expone el conjunto completo de lectores desarrollado para la línea privada 1.4, incluidas las herramientas de inspección de Excel, PDF, imágenes y PyTorch. Sin un complemento, esa familia de herramientas simplemente no se registra; el resto del servidor MCP sigue siendo utilizable.

Esto mantiene la instalación predeterminada centrada en el caso de uso RWX/plano de control, en lugar de obligar a todos los usuarios a instalar grandes dependencias científicas como PyTorch.

Estado del proyecto

Versión actual de preparación pública: 1.4.0rc1.

El repositorio público se crea a partir de una exportación limpia y sin historial de la línea de desarrollo privada probada. El historial privado de Git, la política de producción, el estado de OAuth, los registros, los secretos y la salida de compilación se excluyen intencionadamente.

No objetivos

HostGate no pretende convertirse en:

• un emulador de terminal completo;

• un marco de orquestación de shell;

• un mercado o enrutador de MCP;

• un sustituto multiplataforma de agente de codificación;

• un sandbox completo del sistema operativo.

Las nuevas capacidades solo deben añadirse cuando resuelvan un problema operativo o de seguridad demostrado.

Documentación

• SECURITY.md — límites de seguridad y notificación de vulnerabilidades.

• docs/THREAT_MODEL.md — supuestos, activos protegidos y garantías fuera de alcance.

• docs/control_center.md — arquitectura del Centro de control y transacciones de políticas.

• docs/architecture.md — arquitectura del servidor.

• docs/tools.md — referencia de herramientas de MCP.

• CHANGELOG.md — historial de versiones.

Licencia

Licenciado bajo la Apache License 2.0. Consulte NOTICE para obtener información de atribución.