Skip to main content
Glama
ssh-mcp-guard
by HostCrust
README.md
# Let Claude Code, Codex or Cursor SSH into your servers, with an allowlist enforced on the server, signed approvals and verifiable receipts.

<!-- mcp-name: io.github.HostCrust/ssh-mcp-guard -->

**ssh-mcp-guard** is a free, open-source (Apache-2.0) way to give AI coding agents SSH access to your
Linux servers without giving them a shell. It comes from [HostCrust](https://hostcrust.com) and has
three parts:

- **`hc-gate`** runs on each server as the *forced command* of one SSH key. With that key, sshd runs
  hc-gate and nothing else, whatever the client asks for. hc-gate runs only named actions that a
  root-owned policy allows, and shell is off.
- **`ssh-mcp-guard`** is a local MCP server for Claude Code, Codex and Cursor. Read-only actions
  (status, logs, service status) run straight away. Changes (restart, patch, reboot) wait for you.
- **`hc-approve`** shows you exactly what a change will run and signs it with your SSH key.
  **`ssh-mcp-guard-verify`** checks the server's hash-chained receipts offline.

No dependencies: hc-gate is one Python 3.6+ file on the server; the laptop tools need Python 3.10+
and OpenSSH 8.1+ (`ssh-keygen -Y` first appeared in 8.1). **Version 0.9.0**: it stays below 1.0 until
an outside security review ([SECURITY.md](SECURITY.md)).

## Why client-side rules can be bypassed, and this can't (30 seconds)

```text
 Client-side guard: Claude Code permission rules, hooks, most SSH MCP servers
 ─────────────────────────────────────────────────────────────────────────────
   agent ──► MCP server ──[policy check]──► ssh ──► server: a full shell
     │                                                  ▲
     └──── runs `ssh web-01 'rm -rf /srv'` itself ──────┘   the check never sees it

 ssh-mcp-guard: the check lives in sshd on the server
 ─────────────────────────────────────────────────────────────────────────────
   agent ──► MCP server ──► ssh ─┐
     │                           ├─► sshd ─► hc-gate ─► policy ─► signed approval? ─► run ─► verify ─► receipt
     └──── runs `ssh ...` itself ┘   (this key can't reach anything else)
```

1. **Rules on your laptop only see what goes through them.** An agent that can run shell commands can
   call `ssh` directly and skip the MCP server; mcp-ssh-manager's own README
   [says the same about its approvals](https://github.com/bvisible/mcp-ssh-manager#keep-the-agent-on-the-tools).
   Command allowlists have been bypassed with `$(...)`
   ([example](https://mfyz.com/claude-code-allowlist-command-substitution-bypass/)).
2. **hc-gate is enforced by sshd.** The agent's key is listed in `authorized_keys` with
   `command="/usr/bin/sudo -n /usr/local/bin/hc-gate",restrict`. For every connection with that key,
   sshd runs hc-gate and hands it the requested command as text in `$SSH_ORIGINAL_COMMAND`. hc-gate
   parses that text as an action name plus parameters and never passes it to a shell. `restrict` turns
   off terminals and all forwarding.
3. **So the agent can't route around it with that key**, whether it uses the MCP server, plain `ssh`,
   `$(...)` tricks or anything else. The one condition: it must not have *another* way in, such as
   your own admin key or your ssh-agent (see [Limits](#limits)).

## Install

### On each server (as root)

```sh
curl -fsSLo hc-gate https://raw.githubusercontent.com/HostCrust/ssh-mcp-guard/v0.9.0/ssh_mcp_guard/hc_gate.py
echo "1807add6d87f7ef0eb3292dbca773fb2f53417f483765fe2bd84a3653884d230  hc-gate" | sha256sum -c -
less hc-gate      # read it first: one file, about 1,100 lines, Python standard library only
install -o root -g root -m 0755 hc-gate /usr/local/bin/hc-gate
hc-gate install
```

The checksum is for v0.9.0; each release lists its own. `hc-gate install` creates
`/etc/hc-gate/policy.ini` (read actions on, changes need approval, `shell.run` off),
`/etc/hc-gate/allowed_signers`, `/var/log/hc-gate/` and `/var/lib/hc-gate/`. Running it again keeps
existing files and only checks them. **It never creates users or edits sudoers, `authorized_keys` or
`sshd_config`.** It prints those steps for you to review and run:

```sh
# 1. A user for the agent's key (sshd runs forced commands through its shell; '*' = no password, not locked)
useradd --system --create-home --shell /bin/sh hcgate && usermod -p '*' hcgate
# 2. Let it run hc-gate as root, with no arguments, and nothing else
printf '%s\n' 'Defaults:hcgate env_keep += "SSH_ORIGINAL_COMMAND SSH_CLIENT", !requiretty' \
  'hcgate ALL=(root) NOPASSWD: /usr/local/bin/hc-gate ""' > /etc/sudoers.d/hc-gate
chmod 440 /etc/sudoers.d/hc-gate && visudo -cf /etc/sudoers.d/hc-gate
# 3. In ~hcgate/.ssh/authorized_keys (mode 600, owned by hcgate): the agent's key, restricted
command="/usr/bin/sudo -n /usr/local/bin/hc-gate",restrict ssh-ed25519 AAAA...agent-key... hc-gate
# 4. In /etc/hc-gate/allowed_signers: one line per approver (hc-approve --signer-line prints yours)
alice namespaces="hc-gate" ssh-ed25519 AAAA...your-key... alice@laptop
```

hc-gate needs `python3` on the server's `PATH` (on minimal AlmaLinux/Rocky 8: `dnf install python3`)
and, for approvals, `ssh-keygen` from OpenSSH 8.1 or later. **AlmaLinux and Rocky 8 ship OpenSSH 8.0,
which can't verify approvals**, so there hc-gate refuses every approval and you can use the read-only
policy only. It refuses to run if its own file, its directory, the policy, the approver list or its log
or state directory can be changed by anyone but root.

### On your laptop

```sh
pipx install git+https://github.com/HostCrust/ssh-mcp-guard@v0.9.0   # ssh-mcp-guard, hc-approve, ssh-mcp-guard-verify
ssh-keygen -t ed25519 -N '' -f ~/.ssh/hc-gate_ed25519 -C hc-gate-agent   # the agent's key (step 3 above)
hc-approve --signer-line                                            # your line for allowed_signers (step 4)
```

Install from the release tag (`@v0.9.0`), not `main`. The agent's key has no passphrase because the
MCP server uses it unattended; it can only reach hc-gate. Your approver key is a different key. Already
installed this? `scp "$(ssh-mcp-guard gate-path)" root@server:hc-gate` copies the hc-gate file from your
laptop's install, which you (and so an agent running as you) can change: on the server, run the
`sha256sum -c` line above against the checksum on the release page before you install it.

Then list your servers in `~/.config/ssh-mcp-guard/hosts.ini` (full example in
[`examples/hosts.ini`](examples/hosts.ini)):

```ini
[ssh-mcp-guard]
approver = alice                    # your name in allowed_signers
approver_key = ~/.ssh/id_ed25519    # the key you approve with

[web-01]
ssh = hcgate@203.0.113.10
server_id = web-01-3f9a2c1b         # printed by hc-gate install
identity = ~/.ssh/hc-gate_ed25519
```

Connect once by hand to accept the server's host key and to see the gate answer:
`ssh -i ~/.ssh/hc-gate_ed25519 hcgate@203.0.113.10 diag.status`. The MCP server always passes
`BatchMode=yes` and `StrictHostKeyChecking=yes`, which override your `~/.ssh/config`, so an unknown or
changed host key fails instead of asking. (If your config sets `UserKnownHostsFile /dev/null`, every
connection fails until you point it at a real file.)

## Set up Claude Code, Codex or Cursor

**Claude Code**

```sh
claude mcp add --transport stdio --scope user ssh-mcp-guard -- ssh-mcp-guard
```

Optional but recommended: the [PreToolUse hook](hooks/claude-code-deny-raw-ssh.py) denies raw `ssh`,
`scp`, `sftp` and `rsync` to the hosts in your `hosts.ini` (and `hc-approve` or `ssh-keygen -Y sign`
run by the agent), and tells the agent to use the MCP tools. Copy the file, read it, and add to
`~/.claude/settings.json`:

```json
{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command",
  "command": "python3 /path/to/claude-code-deny-raw-ssh.py"}]}]}}
```

The hook reads command text, so it keeps the agent on the right path but is not the security
boundary; hc-gate is. It complements [dcg](https://github.com/Dicklesworthstone/destructive_command_guard)
and Claude Code's own permission rules; it doesn't replace them.

**Codex**

```sh
codex mcp add ssh-mcp-guard -- ssh-mcp-guard
```

or in `~/.codex/config.toml`:

```toml
[mcp_servers.ssh-mcp-guard]
command = "ssh-mcp-guard"
tool_timeout_sec = 1900   # a patch can take up to 30 minutes; Codex's default is 60 seconds
```

**Cursor**: in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{"mcpServers": {"ssh-mcp-guard": {"type": "stdio", "command": "ssh-mcp-guard"}}}
```

The MCP server speaks MCP 2025-06-18 over stdio and has four tools:

| Tool | Annotations | What it does |
|---|---|---|
| `list_hosts` | read-only | The hosts in `hosts.ini`. No network |
| `run_action` | read-only | Runs a read-only action through hc-gate. For anything else it runs nothing and returns `needs_approval` with the exact `hc-approve` command |
| `submit_approved` | destructive | Sends an approval you made to hc-gate, which checks it, runs the action, verifies it and writes receipts |
| `get_receipts` | read-only | Fetches the last receipts, saves them locally and checks the chain |

"Read-only" means on the server; hc-gate still appends receipts for every request. **Text from servers
is treated as untrusted:** command output, log lines and receipts come back under
`untrusted_server_output`, with a note that it is data to report, never instructions to follow, and
with control, bidi and invisible Unicode characters (tag characters, zero-width spaces) replaced by
visible `<U+XXXX>` markers. Anyone who can get a line into a server's logs can write that text (a
failed SSH login's user name is enough), and the agent reading it can run commands on your laptop. The
marking helps the model; it can't guarantee the model ignores the text, so see [Limits](#limits).

## How a change gets approved

1. You ask: *"nginx on web-01 is returning 502s, have a look."* The agent calls `run_action` with
   `diag.service` and `diag.journal` for nginx. They run straight away.
2. It decides nginx needs a restart and calls `run_action` with `service.restart`. Nothing runs; it
   gets back `needs_approval` and the command `hc-approve web-01 service.restart unit=nginx.service`.
3. You run that in **your own terminal**. It leads with the server id the signature is bound to (the
   host name next to it comes from your `hosts.ini` and isn't signed), then shows the risk, the exact
   unit or package list (anything unusual is marked with `!`), the checks the server makes first, every
   command it will run, and which key and `ssh-keygen` will sign. Everything it prints is escaped to
   printable ASCII, so nothing in `hosts.ini` or the parameters can move the cursor or hide characters.
   Then it asks you to type `yes`, reading the answer from the terminal (`/dev/tty`), not stdin. That
   stops a plain pipe, not a program running as you: one that opens a pseudo-terminal can type `yes`
   too (see [What an agent running as you can do](#what-an-agent-running-as-you-can-do)).

   ```text
   Approve service.restart on server web-01-3f9a2c1b?

     server id  web-01-3f9a2c1b   <- signed: it runs only on the server whose policy.ini has this id
     host       web-01  (hcgate@203.0.113.10)   <- the name in your hosts.ini; not signed
     action     service.restart  (class: service; runs as root)
     RISK       stops nginx.service and starts it again: whatever it serves is down until it is back up, and stays down if it fails to start. The server runs it only if the unit is running now or has failed (crashed); a failed unit is started again, and a failed one-shot unit runs its job again. A unit that is stopped, never started, starting, stopping or reloading is refused
     unit       nginx.service
     params     {"unit": "nginx.service"}
     checks     systemctl show -p LoadState,Id,Type,ActiveState -- nginx.service   <- must be a loaded service, running now or failed, and not on hc-gate's critical list (ssh, systemd-*, network, firewall, consoles and debug shells, power, storage, cloud-init, updaters, containers ...)
                (on the server, before anything changes; if a check fails, nothing runs and the approval stays unused)
     runs       systemctl restart -- nginx.service
                systemctl is-active -- nginx.service   <- verification: must print 'active'
     expires    2026-11-14 12:30 UTC (in 15 min); single use
     signed by  alice with /home/alice/.ssh/id_ed25519  (passphrase-protected)
     using      /usr/bin/ssh-keygen

   Type "yes" to sign: yes

   Approved. Approval id: 3f9a2c1b7d4e (valid until 2026-11-14T12:30:00Z, single use)
   ```

4. You tell the agent *"approved, 3f9a2c1b7d4e"*. It calls `submit_approved`. hc-gate checks the
   signature against `allowed_signers`, that the approval names this server, that it hasn't expired
   and that its nonce was never used. It checks that `nginx.service` is a loaded service that is
   running now (or has failed) and may be restarted. Then it restarts it, checks the unit is `active`, and writes four
   receipts: request, decision, result, verification. Sending the same approval again is refused.

Without an MCP client, it's plain SSH: `ssh -i ~/.ssh/hc-gate_ed25519 hcgate@web-01 'diag.journal
unit=nginx lines=50'` returns JSON, and `hc-approve` also prints the `ssh ... approved <token>` command
to run an approval yourself. Any request can start with `--dry-run`: the gate decides and shows the
exact commands, runs nothing, and doesn't use up an approval. With plain `ssh`, put `--` before the host,
or ssh reads `--dry-run` as its own option: `ssh -i ~/.ssh/hc-gate_ed25519 -- hcgate@web-01 '--dry-run
diag.status'`.

## Actions

The same catalog as the HostCrust agent, so the free gate and the hosted product speak one vocabulary.
Unit and package names must match `[A-Za-z0-9@._+:-]{1,128}` and must not start with `-`.

| Action | Parameters | Default | Runs (argument lists, never a shell string) |
|---|---|---|---|
| `diag.status` | | on | `uptime`, `free -m`, `df -hPl`, `systemctl --failed`, `uname -r`, boot id; reboot-required flag |
| `diag.top` | | on | `ps` top 15 by CPU and by memory |
| `diag.journal` | `unit`, `lines` (1–200, default 100) | on | `journalctl -u UNIT -n LINES --no-pager` |
| `diag.service` | `unit` | on | `systemctl status --no-pager -- UNIT` |
| `inventory.collect` | | on | The read-only [Patch Proof](https://github.com/HostCrust/patch-proof) collector; the MCP server saves the output for `hc-proof report` |
| `gate.receipts` | `last` (1–100000, default 50) | on | Reads the receipt log |
| `service.restart` | `unit`: a `.service` name | approval | Checks `systemctl show -p LoadState,Id,Type,ActiveState -- UNIT` (loaded, a service, active or failed), then `systemctl restart -- UNIT`, then checks `systemctl is-active -- UNIT` |
| `patch.packages` | `packages` (1–200 installed package names) | approval | Checks every name is installed; then apt: `apt-get update`, `apt-get -y --no-remove install --only-upgrade -- PKGS`; dnf/yum: `dnf -y upgrade -- PKGS`. Then the Patch Proof collector |
| `patch.all` | | approval | apt: `apt-get update`, `apt-get -y --with-new-pkgs upgrade`; dnf/yum: `dnf -y upgrade`. Then the collector |
| `system.reboot` | `delay_minutes` (1–1440) or `at` (`HH:MM`) | approval | `shutdown -r +N` or `shutdown -r HH:MM` |
| `shell.run` | `cmd` | **off** | `/bin/sh -c CMD`. Only if you set it to `approval`; even then every command needs a signature |

**What `service.restart` and `patch.packages` will never do** (HostCrust's own security reviews,
14 Nov 2026, findings H1 and H2, and 15 Nov 2026, finding M4):

- `service.restart` takes only `*.service` units, so no `poweroff.target`, `halt.target`,
  `reboot.target`, `suspend.target`, `kexec.target`, `rescue.target`, slices, sockets or mounts.
- It never restarts a critical unit. The list (`CRITICAL_SERVICES` and `CRITICAL_PREFIXES` in
  `hc_gate.py`) is the HostCrust agent's, copied unchanged, and names are compared in lower case:
  - remote access and logins: `ssh`, `sshd`, `ssh@*`, `sshd@*`, `sshd-*`, `dropbear`, display managers
    (`gdm`, `lightdm`, `sddm` ...), `getty@*`, `serial-getty@*`, `container-getty@*`, `console-getty*`,
    `autovt@*`, `user@*`, `user-runtime-dir@*`, and `hostcrust-agent`;
  - root shells and recovery: `debug-shell`, `emergency`, `rescue`, `console-shell`, `friendly-recovery`;
  - power: `halt`, `poweroff`, `reboot`, `shutdown`, `kexec*`, `plymouth*`, offline updates
    (`packagekit-offline*`, `system-update*`);
  - the system: `systemd-*`, `dbus`, `dbus-*`, `polkit*`;
  - storage: `blk-availability`, `multipathd`, iSCSI (`iscsi*`, `iscsid`, `open-iscsi*`), MD and LVM
    (`mdadm*`, `mdmon*`, `mdmonitor`, `dm-event`, `lvm2-*`), `zfs-*`, swap and zram helpers, `rbdmap`;
  - automatic updates: `apt-daily*`, `unattended-upgrades`, `dnf-automatic*`, `yum-cron`;
  - network, VPNs and firewalls: `networking`, `network`, `NetworkManager*`, `network-manager`, `netplan-*`, `ifup@*`,
    `ifupdown*`, `dhcpcd*`, `dhclient*`, `wicked*`, `wg-quick*`, `openvpn*`, `strongswan*`, `ipsec`,
    `tailscaled`, `zerotier-one`, `nftables`, `iptables`, `ip6tables`, `firewalld`, `ufw`,
    `netfilter-persistent`, `ebtables`, `ipset`, `shorewall`, `shorewall6`, `csf`, `lfd`;
  - containers: `docker`, `containerd`, `kubelet`, `crio`, `cri-o`, `k3s`, `k3s-agent`, `rke2-server`,
    `rke2-agent`;
  - cloud-init: `cloud-init*`, `cloud-config*`, `cloud-final*`.
- Before anything runs, the server's systemd must report the unit as loaded, as a service, under a name
  (aliases resolved) that isn't on that list, and **running now or failed** (`ActiveState` `active` or
  `failed`). Restarting a crashed service is what `service.restart` is for. Every other state is
  refused: `systemctl restart` also *starts* a unit that isn't running, so an approved "restart" of a
  unit that was stopped or never started (such as `debug-shell.service`), or one that is starting,
  stopping or reloading, could otherwise start something new. A failed one-shot unit (a boot script,
  say) runs its job again, so read the unit name.
- `patch.packages` refuses names ending in `-`, `+` or `=`, which apt reads as remove, install or a
  version; `openssh-server-` would remove OpenSSH. It also refuses names containing `* ? [ ] ^ $ / @ % ~`
  (patterns, paths, groups). Each name must exactly match an installed package: dpkg's `${Package}` or
  `${Package}:${Architecture}`, or rpm's `%{NAME}`, checked with `rpm -q` per name. So apt never falls
  back to a pattern such as `nginx.-`. `--` comes before the list, and apt runs with `--no-remove`, so
  it aborts rather than remove anything.
- If a check fails, nothing runs and the approval is not used up.

Read-only actions can be `on`, `approval` or `off`. Everything else can only be `approval` or `off`:
there is no way to let a change run without a signed approval. apt runs non-interactively, keeps your
config files, and never restarts services on its own (`NEEDRESTART_MODE=l`); restarts stay separate,
approved actions. Output is capped at 64 KB per stream; patches time out after 30 minutes, everything
else after 2.

## Policy examples

`/etc/hc-gate/policy.ini` must be owned by root and not writable by group or others. Unknown sections,
keys or actions are errors, so a typo can never widen what runs. Three ready-made policies are in
[`examples/`](examples/):

- [`policy-readonly.ini`](examples/policy-readonly.ini): diagnostics only; every change is `off`. No approvers needed.
- [`policy-webserver.ini`](examples/policy-webserver.ini): diagnostics, plus `service.restart = approval` (`.service` units that are running or failed, never a critical one).
- [`policy-patching.ini`](examples/policy-patching.ini): diagnostics, plus approved patches (installed packages only, never a removal), restarts and reboots.

```ini
[gate]
server_id = web-01-3f9a2c1b
# approvals valid for longer are refused (put comments on their own line: hc-gate allows no inline ones)
max_approval_minutes = 60

[actions]
diag.status = on
diag.journal = on
service.restart = approval
patch.all = off
shell.run = off
```

## Receipts you can check

Every request adds lines to `/var/log/hc-gate/receipts.jsonl`: request, decision, and if it ran, result
and verification. Each line's `hash` is `sha256(prev || canonical_json(record))`, the same rule as the
HostCrust app. Receipts keep hashes of command output, never the output itself.
[`docs/receipts.md`](docs/receipts.md) has the format and a sample chain you can check yourself.

```sh
ssh-mcp-guard-verify receipts.jsonl                 # OK    214 receipts, seq 1..214, head cfdee583...
ssh-mcp-guard-verify receipts.jsonl --expect HEAD   # a head you saved earlier must still be there
```

**Verification after changes:** after `service.restart`, the unit must be `active` or the result is
`failed`. After `patch.packages` or `patch.all`, hc-gate records which package versions changed and
takes a [HostCrust Patch Proof](https://github.com/HostCrust/patch-proof) inventory with the same
collector Patch Proof publishes (embedded byte for byte), and writes its SHA-256 into the receipt. The
MCP server saves the inventory locally, so you can run `hc-proof report --input <file>` and see which
CVEs are really fixed, and anyone can match the file to the receipt.

## How it compares

We have **not** run these tools side by side. Every cell about another tool comes from its own
documentation, as linked, checked on 14 Nov 2026. The last column says where each one does more.

| | Where the policy is enforced | Allowlist by default | Approval bound to the exact action | Receipts verifiable offline | Checks the result | Codex / Cursor | Where it's better |
|---|---|---|---|---|---|---|---|
| **ssh-mcp-guard** | **On the server**: sshd forced command, then hc-gate | Yes: 11 named actions, shell off | Yes: SSH signature over server, action, parameters, nonce and expiry; single use | Yes: hash chain, always on, plus `ssh-mcp-guard-verify` | Unit active after a restart; Patch Proof inventory hash after a patch | Yes; the gate also works with plain `ssh` | See [Limits](#limits) |
| [tufantunc/ssh-mcp](https://github.com/tufantunc/ssh-mcp) (MIT) | In the MCP process on your machine | Read-only commands allowed by a per-command argument grammar; other commands are classified | MCP elicitation prompt, by default for destructive commands | JSONL audit log; a hash chain with `--auditTamperEvident` (off by default); no verifier documented | Not documented | Cursor documented; Codex not mentioned | Arbitrary commands with per-argument classification, roles by host group, OPA, secret redaction, signed build attestations |
| [classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server/blob/main/README_EN.md) (ISC) | In the MCP process | Only with `--whitelist` regexes | None documented | None documented | No | Cursor mentioned | SFTP path allowlist, many hosts, optional HTTP transport |
| [bvisible/mcp-ssh-manager](https://github.com/bvisible/mcp-ssh-manager) (MIT) | In the MCP process, plus a local control app | `unrestricted` by default; `readonly` or allow/deny patterns per server ([modes](https://github.com/bvisible/mcp-ssh-manager/blob/main/docs/SECURITY_MODES.md)) | Optional, per server (`never` by default, `destructive` or `always`), answered in a desktop or browser app | JSONL audit trail, no hash chain | No | Codex documented; any MCP client | A GUI, an encrypted credential vault, many more tools, and its own Claude Code guard hook |
| [raforg/sshdo](https://github.com/raforg/sshdo) (GPL-2.0+) | **On the server** (forced command) | Yes: exact commands in `/etc/sshdoers` | No | syslog | No | Any SSH client; no MCP | A training mode that learns the allowlist from real use; any exact command line you list |
| [dcg](https://github.com/Dicklesworthstone/destructive_command_guard) ([MIT with an OpenAI/Anthropic rider](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/LICENSE)) | A hook in the agent, on your machine | A denylist of destructive patterns (50+ packs) | An `ask` mode where the agent's hook protocol supports it | Optional SQLite history | No | Claude Code, Codex CLI, Cursor and many more | Guards every local command (git, rm, databases) across a dozen agents |
| [hoop.dev](https://github.com/hoophq/hoop) (MIT) | A gateway in front of servers and databases | Guardrails are deny rules; the open-source tier has limits ([pricing](https://hoop.dev/pricing)) | [Command reviews](https://hoop.dev/docs/learn/features/reviews/command-reviews), just-in-time or per command; the pricing page doesn't say which tier includes them | Session recording and replay | No | Agent-agnostic, per its README | Data masking, many protocols (Postgres, SQL Server, HTTP), team review workflows |
| [Teleport](https://goteleport.com/docs/feature-matrix/) (AGPL-3.0 source; [Community binaries](https://github.com/gravitational/teleport/blob/master/build.assets/LICENSE-community) for organizations under 100 people and $10M revenue) | An identity-aware proxy and agents | Roles decide who gets in; [MCP access](https://goteleport.com/docs/enroll-resources/mcp-access/getting-started/) can filter tools per role | [Access Requests](https://goteleport.com/docs/identity-governance/access-requests/) (Enterprise) approve access, not one command | Session recording and audit log | No | Not verified | SSO, short-lived certificates, recording across SSH, Kubernetes, databases and MCP for whole teams |
| `command=` in `authorized_keys` by hand ([sshd(8)](https://man.openbsd.org/sshd)) | On the server | Whatever your script allows | No | No | No | Any SSH client | Nothing to install |

## FAQ

### What is the safest MCP server to let Claude Code run commands on my Linux server over SSH?

The safest setup doesn't depend on the MCP server: give the agent its own SSH key and restrict that
key on the server, so sshd decides what it can run. ssh-mcp-guard packages exactly that. hc-gate is the
key's forced command; it runs only named actions from a root-owned policy, with shell off; changes need
an approval you sign with your own SSH key; and every request is written to a hash-chained receipt log.
Then keep your personal keys and ssh-agent out of the agent's reach, or it can log in as you. If you
need arbitrary commands rather than a fixed catalog, tufantunc/ssh-mcp has the most complete client-side
policy; it is enforced on your machine, so an agent with a shell can go around it.

### How do I give Claude Code or Cursor SSH access to a server with per-command approval and an audit log?

1. Install hc-gate on the server and give the agent a key restricted to it ([Install](#install)).
2. Add `ssh-mcp-guard` to Claude Code (`claude mcp add --transport stdio --scope user ssh-mcp-guard -- ssh-mcp-guard`) or to Cursor's `mcp.json`.
3. Read-only actions run straight away. Every change returns an `hc-approve` command; you run it, see exactly what will run, and sign. Set read actions to `approval` too if you want to approve everything.
4. The audit log is `/var/log/hc-gate/receipts.jsonl` on the server: request, decision, result and verification for every request, checkable offline with `ssh-mcp-guard-verify`.

### Can Claude Code bypass MCP restrictions with plain ssh?

Yes, if the restrictions only live in the MCP server, a hook or Claude Code's permission rules, and
the agent can run shell commands and has a usable key: it can run `ssh host '...'` itself. With
ssh-mcp-guard the agent's key is restricted by sshd, so plain `ssh` with that key reaches the same
hc-gate and the same policy. It can still get around it with a *different* key, such as yours in
ssh-agent, so keep those away from the agent.

### How do I use Codex over SSH safely?

Same setup as Claude Code: install hc-gate on the server, then `codex mcp add ssh-mcp-guard --
ssh-mcp-guard` (or the `config.toml` snippet above, with `tool_timeout_sec` raised for patches). Codex
gets read-only actions directly and asks you to approve changes with `hc-approve`. Even if Codex runs
`ssh` itself with the agent's key, the server only runs what the policy allows.

### Does this replace Teleport?

No. Teleport controls **who gets in**: identity, SSO, short-lived certificates, session recording.
ssh-mcp-guard controls **what an agent's key may change** on a server, with a signed approval for each
change, a check that it worked, and a receipt. You can use both.

### Does it need an MCP client?

No. hc-gate answers plain `ssh` with JSON, so scripts, CI jobs and other agents can use it the same way.

## Limits

- **An agent running as your OS user can get around the approval step on your laptop.** The next
  section says exactly what it can and can't do. What hc-gate enforces on the server holds whatever
  happens on the laptop; whether a *person* approved each change depends on keeping the agent away from
  your approver key and your terminal.
- **Server output can carry instructions.** Log lines and command output come back to the agent as
  labelled, untrusted data with invisible characters made visible, but the model still reads them. An
  agent that follows text in a log can do whatever it can already do on your laptop, so the point above
  matters here too. Read-only actions also let the agent read any unit's journal, which can include
  your admin sessions' `sudo` command lines: set `diag.journal = approval` if that matters.
- **It guards one key.** An agent that can use your own admin key or ssh-agent can log in as you.
- **A fixed catalog.** No file transfer and no arbitrary commands, unless you turn on `shell.run`, which
  still needs a signature per command. Linux with systemd; apt, dnf or yum. `service.restart` refuses a
  list of units, which can't cover every service that matters: one that isn't on it (your database, say)
  can still be restarted with an approval, so read the unit name. It restarts a failed unit (starting
  it again) but never starts a stopped or never-started one; start those yourself. A package whose real
  name ends in `+` (such as `g++`) can only be upgraded with `patch.all`.
- **AlmaLinux and Rocky 8** ship OpenSSH 8.0, whose `ssh-keygen` can't verify approvals: there hc-gate
  refuses every approval, so use the read-only policy.
- **Receipts are per server,** and root on that server could rewrite them. Keep head hashes elsewhere
  (`get_receipts` saves copies locally) and check them with `ssh-mcp-guard-verify --expect`.
- **Verification is narrow:** a restart is checked with `systemctl is-active`; a patch records an
  inventory hash (use Patch Proof to judge CVEs); a reboot is only checked as scheduled (compare the
  boot id in `diag.status` afterwards).
- **The hook is a speed bump, not a boundary.** It reads command text, so `a=ssh; $a host`, a script
  file, `python3 -c`, git's `core.sshCommand` or ansible get past it. hc-gate is what enforces.
- **New and not yet independently reviewed** (hence 0.9.0). HostCrust reviewed it twice itself (14 and
  15 Nov 2026); the fixes are listed in [SECURITY.md](SECURITY.md), with the known gaps still open.
  Tested with unit tests (on macOS; the CI workflow runs them on Linux too) and end to end on test
  servers: this version on Debian 12 (OpenSSH 9.2, sudo 1.9.13, systemd 252) and AlmaLinux 9.8 (OpenSSH
  9.9, sudo 1.9.17, systemd 252, SELinux disabled) on 15 Nov 2026, and an earlier build on Ubuntu 24.04
  (OpenSSH 9.6, sudo 1.9.15). That covered signed restarts of running and failed services, refused
  critical, aliased and never-started units, signed apt and dnf upgrades, refused package-name tricks,
  replays, a damaged nonce store (ext4 and xfs) and a client hanging up mid-action. Not yet run on
  AlmaLinux or Rocky 8, with SELinux enforcing, or with a FIDO approver key. Start with the read-only
  policy on servers that matter.

### What an agent running as you can do

hc-approve, your approver key, `hosts.ini`, the pipx install of these tools and your shell's startup
files all belong to your OS user. An agent that runs as that user with no sandbox around it can reach
all of them; a sandbox that limits what it can read and write narrows this, so check what yours
allows. hc-approve reads your answer from the terminal
(`/dev/tty`), so a plain pipe can't answer it. That is not a protection against such an agent: in
HostCrust's review of 15 Nov 2026 a program that opened a pseudo-terminal typed "yes" and got a signed
`system.reboot` approval with no person involved.

- **With an approver key that has no passphrase,** the agent can sign any approval itself, with
  `ssh-keygen -Y sign` or by driving hc-approve through a pseudo-terminal. hc-approve flags such a key
  on every approval (`! key  it has no passphrase`).
- **With a passphrase that is unlocked in your ssh-agent,** the same: `ssh-keygen -Y sign` can use a key
  the agent holds without asking. Don't load the approver key into ssh-agent (a FIDO key in ssh-agent
  still needs its touch).
- **With a passphrase or a FIDO security key** (`ssh-keygen -t ed25519-sk`, a touch per signature), it
  can't sign without you typing the passphrase or touching the key. It can still change *what* you
  sign, or capture the passphrase:
  - edit `hosts.ini` so the host name you approve for points at another server's id. hc-approve leads
    with the signed server id and flags an id that doesn't start with the host name; read it;
  - patch hc-approve in its pipx folder, or alias `hc-approve` in your shell's startup files, so the
    screen shows one thing and it signs another;
  - put a fake `ssh-keygen` where hc-approve looks, to capture the passphrase. hc-approve ignores your
    `PATH` and uses `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin`, then `/usr/local/bin` and
    `/opt/homebrew/bin` (often writable by you); the screen names the one it uses and flags it if you
    can write to it.
- **What it can't do, with any key:** make hc-gate run an action the server's policy doesn't allow, run
  a change without a valid signature from a key in the server's `allowed_signers`, use an approval
  twice, use one on a server with another `server_id`, or change the parameters that were signed.

**What actually keeps your approvals yours:** run the agent as a **different OS user**, or in a
container or VM that can't read your home directory (approver key, `hosts.ini`, the tools' install,
shell startup files), or approve on **another device**, so the approver key never sits on the agent's
machine.

See [SECURITY.md](SECURITY.md) for the full threat model.

## Credits and licence

Apache-2.0, © 2026 DigiRDP, LLC (HostCrust). Restricting an agent's key with `command=` was suggested
in the Ask HN thread ["How do you safely give LLMs SSH/DB access?"](https://hn.svelte.dev/item/46620990);
[sshdo](https://github.com/raforg/sshdo) showed the forced-command allowlist years earlier.
Contributions: [CONTRIBUTING.md](CONTRIBUTING.md).

Made by HostCrust, guarded operations for Linux servers (early access): https://hostcrust.com/tools/ssh-mcp-guard/

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation4/5

list_hosts, run_action, and submit_approved have clear boundaries: read-only vs. approval-gated execution is explicitly spelled out. The one overlap is receipts: run_action supports gate.receipts {last} while get_receipts fetches the last receipts, saves them and verifies the chain, so an agent could plausibly pick either for 'see recent activity'.

Naming Consistency4/5

All four names are snake_case verb_noun (list_hosts, run_action, get_receipts), matching the dominant convention. submit_approved uses a past participle rather than a noun object (submit_approval would be stricter), a minor deviation in an otherwise predictable set.

Tool Count4/5

Four tools map cleanly onto the workflow stages (discover hosts, run read-only actions, execute approved actions, verify receipts) with no filler. It is on the thin side of the 3-15 range and leaves little room for auxiliary operations like approval inspection.

Completeness4/5

The core loop read-only diagnostics -> approval -> execution -> auditable receipts is fully covered, including local saving and chain verification. Gaps are modest but real: there is no way to list or poll pending approvals, and host entries cannot be added or removed, only listed.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues