Secure Host MCP

Secure Host MCP exposes a Windows, Linux, or macOS host terminal to remote MCP clients through Streamable HTTP. It is intentionally powerful: the default administrator token can execute any command available to the service account, inspect or launch configured tunnels, and request privileged operations.

Download a standalone release

Download the archive for your platform from GitHub Releases:

• Windows x64: extract the ZIP and double-click secure-host-mcp.exe. On first launch the console wizard asks about public-IP and Cloudflare Tunnel access, configures the administrator token, displays the connection URLs, and starts both servers.

• Linux x64: extract the tar.gz archive and run ./secure-host-mcp launch for the same first-run initialization and startup behavior.

• macOS Apple Silicon: extract the tar.gz archive and run ./secure-host-mcp launch. The archive currently targets arm64 Macs only.

No separate Node.js installation is required for these archives. The Windows executable is not code-signed yet, so Microsoft Defender SmartScreen may display an unknown-publisher warning. Verify the download against SHA256SUMS.txt before running it.

# Windows PowerShell
(Get-FileHash .\secure-host-mcp-0.1.0-windows-x64.zip -Algorithm SHA256).Hash

# Linux / macOS
sha256sum -c SHA256SUMS.txt --ignore-missing

Related MCP server: win-cli-mcp-server

Install and first setup

Requires Node.js 20 or newer when installed through npm:

npm install -g secure-host-mcp
secure-host-mcp setup --public-url https://mcp.example.com
secure-host-mcp doctor
secure-host-mcp start

First run: the required first command is setup, not start.

A fresh installation has no administrator token yet. setup creates it (written to tokens.json), records the base configuration, and prints your connection URLs. start only launches servers that are already configured — on a machine that has never run setup it exits immediately with ADMIN_TOKEN_MISSING: Run setup before starting the server.

The first-run flow is therefore: 1. setup (once per machine) → 2. doctor (optional health check) → 3. start (every launch afterwards). If you prefer a single command, secure-host-mcp launch runs the first-time setup automatically when needed and then starts the servers — the same behavior as double-clicking secure-host-mcp.exe from the standalone package.

When run in an interactive terminal for a new installation, setup:

1. Asks whether the device has a directly reachable public IP and detects it through Cloudflare's trace endpoint when possible.

2. Inspects cloudflared and offers to install the checksum-verified official binary when it is missing. Installing the binary does not create a Cloudflare account or tunnel configuration.

3. Lets you automatically generate the initial token or enter any non-empty token of your choice. There is no fixed token format; letters, numbers, and combinations are accepted.

4. Explains that the same initial token is both the web-console administrator token and a full-access MCP Bearer token.

5. Prints concrete public-IP MCP and web-console URLs when a public IP is available, plus a plaintext HTTP warning.

Non-interactive setup keeps automation compatibility: it generates the token without prompting and does not install Cloudflare automatically. New installations listen on all network interfaces by default so remote clients can connect when the host firewall, router, and cloud security rules permit it.

Endpoints default to:

• MCP and OAuth: http://0.0.0.0:8767/mcp

• Administration: http://0.0.0.0:8768/

0.0.0.0 is a bind address, not a client URL. Connect with the server's IP address or DNS name. Both services start even when HTTPS is not configured, but authentication does not encrypt bearer tokens, OAuth codes, or administration traffic. ChatGPT requires a remotely reachable HTTPS MCP URL. Put Caddy, Nginx, Cloudflare Tunnel, frp, or another trusted reverse proxy in front of port 8767, and protect remote administration on port 8768 with HTTPS or a trusted private network. A minimal Caddy example is under examples/.

The administration URL serves a responsive bilingual dashboard after the administrator token is entered. It shows host resources and runtime configuration, creates and revokes scoped connection tokens, and controls configured frpc/cloudflared processes. Dashboard-created connection tokens are written to the same tokens.json registry used by setup and manual configuration.

For example, when setup detects 203.0.113.10, it prints:

Public MCP URL: http://203.0.113.10:8767/mcp
Web console URL: http://203.0.113.10:8768/
WARNING: HTTP is plaintext...

ChatGPT OAuth connection

Use https://mcp.example.com/mcp as the server URL and choose OAuth. The server publishes its authorization and protected-resource metadata. A new client dynamically registers, ChatGPT opens the authorization page, and the host administrator enters the administrator token and approves the requested scopes. The server uses authorization code + PKCE and issues rotating refresh tokens with offline access.

Full write-capable MCP support in ChatGPT depends on the account/workspace plan and current Developer Mode availability.

Terminal and jobs

The main MCP tools are execute_command, start_job, job_status, read_job_output, and cancel_job. Windows uses PowerShell 7 when available and Windows PowerShell otherwise. Linux uses /bin/bash unless configured differently.

Commands are not sandboxed or allowlisted. Run the service under a dedicated account unless full user/root access is intentional. execute_elevated fails closed until the process is already elevated or a privileged helper is installed. set_admin_mode records the request; service reconfiguration must be applied by an installed service adapter or the local CLI.

cloudflared and frpc

secure-host-mcp tunnel inspect
secure-host-mcp tunnel install-plan cloudflared
secure-host-mcp tunnel install-plan frpc
secure-host-mcp tunnel install cloudflared --yes
secure-host-mcp tunnel start cloudflared

The inspector searches PATH and standard cloudflared configuration directories. External-runtime detection currently covers only the official default Windows service named Cloudflared and the Linux cloudflared.service unit; custom service names, template units, bare processes, and macOS launchd services are not detected. Set tunnels.frpcConfig for frpc. Parsed configuration is recursively redacted. frpc verify -c runs before launch. tunnels.proxyUrl is passed as HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, including socks5:// URLs supported by the selected tunnel client.

The install command requires --yes, downloads only the matching official GitHub Release asset, requires its published SHA-256 digest, verifies it, and installs to the application data directory. Without confirmation it fails closed.

Privileged helper

Normal service-account execution is the default. To enable per-command elevation, start the helper separately from an already elevated terminal:

# Windows: run PowerShell as Administrator
secure-host-mcp helper

sudo secure-host-mcp helper

The helper listens only on 127.0.0.1:8769, authenticates with a random key from the restricted secrets file, independently verifies that it is elevated, and audits complete command input/output. set_admin_mode(enabled=true) asks the helper to persist the mode, stop the ordinary instance, and start a new root/Administrator instance. Returning to a lower-privilege account requires restoring the configured Windows Service/systemd account locally; configuration alone is never treated as proof of elevation.

Security choices

• The configured administrator token has all scopes and is accepted by the web console, OAuth approval page, and direct MCP Bearer authentication.

• ~/.secure-host-mcp/tokens.json is the single registry for the administrator token and direct MCP connection tokens. OAuth grants and helper secrets live separately in secrets.json. Both files must use mode 0600 on POSIX. Back them up and protect them.

• Audit logs intentionally contain complete commands and stdout/stderr in plaintext. They rotate by size/day and are retained for 30 days under the data directory.

• MCP and administration listen on all interfaces by default. Every administration API request requires the administrator bearer token, and mutations also require the page CSRF token.

• Public HTTP is not encrypted: authentication controls access but cannot prevent interception of bearer tokens, OAuth codes, or administration traffic. Prefer HTTPS or a trusted VPN.

• Tool annotations ask compatible clients to confirm destructive operations. The host cannot prove that a client actually displayed a human confirmation.

Configuration

Set SECURE_HOST_MCP_HOME to change the data directory. Copy fields from config.example.json into the generated config.json, then restart. Configuration and secrets are written atomically.

The generated tokens.json is intentionally editable:

{
  "version": 1,
  "adminToken": "my-admin-token",
  "connectionTokens": [
    {
      "id": "second-agent",
      "token": "agent-2-token",
      "label": "Second agent",
      "scopes": ["system.read", "command.run"]
    }
  ]
}

Change adminToken to rotate the administrator token, or append entries to connectionTokens to create more direct MCP Bearer tokens. id is optional for manually added tokens; when omitted, the service derives a stable identifier from the token value. Token values have no pattern requirement but must be non-empty and unique. Scopes must come from system.read, command.run, command.elevate, tunnel.read, tunnel.manage, and admin.manage. Restart Secure Host MCP after manual edits. See tokens.example.json for a full-access example.

For a loopback-only deployment, explicitly set both mcp.host and admin.host to 127.0.0.1. New installations enable remote administration by default.

External OIDC can be enabled with auth.externalIssuer and auth.externalAudience. Tokens are verified against the issuer JWKS and mapped to the same MCP scopes.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

Standalone release builds use npm run package:standalone. Cross-platform artifacts should be produced and checksummed in release CI.

Publishing a release

Use Conventional Commit prefixes such as fix:, feat:, and feat!: when merging product changes into main. Release Please automatically creates or updates a Release PR containing the next package.json/lockfile version and CHANGELOG.md. While the project is below 1.0.0, both fix: and feat: produce patch releases; breaking changes retain their normal SemVer meaning.

Merging the Release PR creates the matching v<version> tag and GitHub Release. The release workflow then tests and packages Windows x64, Linux x64, and macOS arm64, creates checksums, uploads all three assets to that Release, and publishes the same version to npm.

By default the Release PR waits for a manual merge, keeping an explicit review gate. When the RELEASE_PLEASE_TOKEN secret (a fine-grained PAT with Actions, contents, and pull-request read/write access) is configured, the workflow approves the validation runs that GitHub holds for a GITHUB_TOKEN-created Release PR and then enables GitHub auto-merge. The PR merges on its own once the required status checks pass. Auto-merge additionally requires the repository setting "Allow auto-merge" and a main branch protection rule with required status checks — without required checks, auto-merge would not wait for CI.

Explicit matching tags and guarded manual workflow runs remain available for recovery and prereleases. Prerelease versions use npm's next dist-tag; stable versions use latest.

The npm job uses Trusted Publishing with GitHub OIDC and does not require a long-lived npm token in repository secrets. A manual workflow run defaults to validation only and will not publish unless explicitly enabled.