Free and open source · Apache-2.0
ssh-mcp-guard: SSH for AI agents, with every change signed and enforced on the server
Let Claude Code, Codex or Cursor read your servers freely, while every change waits for a signature the server itself checks.
ssh-mcp-guard is a free, open-source (Apache-2.0) SSH MCP server for Claude Code, Codex and Cursor. An AI agent can read server status and logs freely, but every change waits for a human approval signed with your SSH key, and the server itself checks the signature.
The check runs on the server, as the forced command of the agent's SSH key, so even plain ssh with that key reaches it. Version 0.9.0 is a pre-release that hasn't had an outside security review.
# On each server, as root
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 -
install -o root -g root -m 0755 hc-gate /usr/local/bin/hc-gate && hc-gate install
# On your laptop
pipx install git+https://github.com/HostCrust/ssh-mcp-guard@v0.9.0
- License
- Apache-2.0
- Version
- 0.9.0 (November 14, 2026)
- Runs on
- Linux servers with systemd (hc-gate), macOS or Linux laptops (MCP server, hc-approve)
- Needs
- Server: Python 3.6+, sudo, systemd, apt or dnf, OpenSSH 8.1+ for approvals. Laptop: Python 3.10+ and OpenSSH 8.1+. No other dependencies
- Written in
- Python
What is ssh-mcp-guard?
ssh-mcp-guard gives AI coding agents SSH access to Linux servers without giving them a shell. It has four parts:
hc-gateruns on each server as the forced command of the agent's SSH key. It runs only named actions that a root-owned policy allows. Shell access is off.ssh-mcp-guardis the local MCP server. Read-only actions run straight away; changes wait for you.hc-approveshows exactly what a change will run, then signs it with your SSH key.ssh-mcp-guard-verifychecks the server's receipt log offline, recomputing its SHA-256 hash chain with the rule written out indocs/receipts.md.
No dependencies: hc-gate is one Python file of about 1,100 lines, small enough to read before you install it.
Why is giving an AI agent SSH access risky?
An agent that can run shell commands and use an SSH key can do anything that key can do. It doesn't have to be hostile: it can be wrong, or be steered by text it reads, such as a crafted user name in a log. That's the core AI agent security problem with SSH.
Most agent safety features run on the client: prompts in an SSH MCP server, the agent's permission rules, and hooks. They only see what goes through them:
- An agent with a terminal can call
sshitself and skip the MCP server. mcp-ssh-manager's README says so about its own approvals: then “none of it applies.” - Rules that match command text can be sidestepped. A February 2026 write-up showed an allowlisted Claude Code command running an unlisted one through
$(...), as of that date; we haven't re-tested it. - Claude Code's documentation calls its hook pattern filter best-effort, and says a timed-out PreToolUse hook doesn't block the call by default.
Client-side checks still catch mistakes, but they aren't the last word. ssh-mcp-guard puts that on the server, in sshd, where the agent can't edit it.
How does ssh-mcp-guard work?
ssh with the agent's key reaches the same gate as the MCP server. The gate guards one key: an agent that can use your own key or ssh-agent can log in as you.Reads run, changes wait
The policy file, /etc/hc-gate/policy.ini, sets each action to on, approval or off. Only read-only actions can be on, so no setting lets a change run unsigned, and a typo is an error, not a wider policy. The defaults:
| Action | What it does | Default |
|---|---|---|
diag.status, diag.top | Uptime, memory, disk, failed units, top processes | on |
diag.journal, diag.service | Up to 200 journal lines, or systemctl status, for one unit | on |
inventory.collect, gate.receipts | The Patch Proof package inventory; the receipt log | on |
service.restart | Restart one running or failed .service unit, then check it | approval |
patch.packages, patch.all | Upgrade named packages, or all, with apt, dnf or yum | approval |
system.reboot | Schedule a reboot | approval |
shell.run | Any command, through /bin/sh | off |
The forced command
The agent's key sits in a dedicated user's authorized_keys with a forced command:
command="/usr/bin/sudo -n /usr/local/bin/hc-gate",restrict ssh-ed25519 AAAA...agent-key... hc-gate
For every connection with that key, sshd ignores the command the client asked for and runs hc-gate, passing the request in SSH_ORIGINAL_COMMAND. hc-gate parses it as an action plus parameters and never hands it to a shell. restrict turns off terminals and forwarding. Through the MCP server, plain ssh or $(...) tricks, that key reaches hc-gate and nothing else.
Signed approvals, nonces and replay protection
An approval names the server id, the action, its exact parameters, a 128-bit random nonce, an expiry and the approver. hc-approve signs it with ssh-keygen -Y sign, built into OpenSSH since 8.1, in the namespace hc-gate, so a signature made for something else, such as a git commit, doesn't count. hc-gate checks it with ssh-keygen -Y verify against the root-owned /etc/hc-gate/allowed_signers.
The gate refuses an approval for another server's id, an expired one, one valid longer than the policy allows, and any nonce it has already seen. It also checks the target first: a restart needs a loaded .service unit that is running or failed and isn't on a long never-restart list (SSH, systemd, networking and more), and each package must exactly match an installed one. If a check fails, nothing runs and the approval stays unused.
A change, step by step
Say nginx on web-01 returns 502s. The agent runs diag.service and diag.journal at once. When it wants a restart, run_action runs nothing and returns hc-approve web-01 service.restart unit=nginx.service. You run that in your own terminal. This is its real screen, up to the prompt:
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@web-01) <- 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 19:00 UTC (in 15 min); single use
signed by alice with ~/.ssh/id_ed25519 (passphrase-protected)
using /usr/bin/ssh-keygen
Type "yes" to sign:
Type yes and it prints an approval id. (We typed no; nothing was signed.) The agent sends the approval with submit_approved, and hc-gate checks it, restarts nginx, checks that it's active and writes four receipts. Sending it again is refused.
Receipts
Every request, refused ones included, adds hash-chained lines to /var/log/hc-gate/receipts.jsonl: request, decision, and if it ran, result and verification. Output is stored only as a hash. We checked the sample chain from docs/receipts.md, then changed one unit name:
$ ssh-mcp-guard-verify sample.jsonl
OK 7 receipts, seq 1..7, head cfdee5835efaeca9c7eafe3973e58cec1f95a9c6b882aaabdeae07adfb495240
note keep the head hash somewhere else; checking it later with --expect also detects receipts removed from the end
$ sed 's/"nginx.service"}}/"sshd.service"}}/' sample.jsonl > tampered.jsonl
$ ssh-mcp-guard-verify tampered.jsonl; echo "exit $?"
FAIL line 4 (seq 4): hash does not match its contents: this receipt was changed
exit 1
Root on the server can still rewrite the chain, so keep a recent head hash off the server (get_receipts saves copies on your laptop) and check it later with ssh-mcp-guard-verify --expect.
Install ssh-mcp-guard
Install from the release tag, v0.9.0, not main. On each server, as root:
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
install -o root -g root -m 0755 hc-gate /usr/local/bin/hc-gate
hc-gate install
hc-gate install writes the default policy and an empty approver list. It never creates users or edits sudoers, authorized_keys or sshd_config; it prints those steps for you to review and run. On your laptop:
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
hc-approve --signer-line # your line for allowed_signers
The agent's key has no passphrase, since the MCP server uses it unattended, and it can only reach hc-gate. Approve with a different key that has a passphrase or lives on a FIDO security key.
Set up Claude Code SSH access with ssh-mcp-guard
List your servers in ~/.config/ssh-mcp-guard/hosts.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@web-01
server_id = web-01-3f9a2c1b # printed by hc-gate install
identity = ~/.ssh/hc-gate_ed25519
Connect once by hand to accept the host key (ssh -i ~/.ssh/hc-gate_ed25519 hcgate@web-01 diag.status), because the MCP server refuses unknown host keys. Then add it to Claude Code:
claude mcp add --transport stdio --scope user ssh-mcp-guard -- ssh-mcp-guard
Claude Code gets four tools: list_hosts, run_action, submit_approved and get_receipts. Server output comes back labeled as untrusted data, with invisible characters made visible.
Add the hook that blocks raw ssh
The repository's PreToolUse hook, hooks/claude-code-deny-raw-ssh.py, denies ssh, scp, sftp and rsync to hosts in your hosts.ini, and stops the agent running hc-approve or ssh-keygen -Y sign. Read it, then add it to ~/.claude/settings.json:
{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command",
"command": "python3 /path/to/claude-code-deny-raw-ssh.py"}]}]}}
It reads command text, so a variable (a=ssh; $a web-01), a script or python3 -c gets past it. It keeps a well-behaved agent on the guarded path; hc-gate is what enforces.
Codex and Cursor: run codex mcp add ssh-mcp-guard -- ssh-mcp-guard and set tool_timeout_sec = 1900 in ~/.codex/config.toml, since a patch can take 30 minutes. For Cursor, add the server to ~/.cursor/mcp.json as the README shows. Scripts can use plain ssh, which returns JSON.
What does ssh-mcp-guard refuse?
hc-approve refuses the worst requests before anything is signed. On our Mac:
$ hc-approve web-01 service.restart unit=poweroff.target
hc-approve: service.restart takes a .service unit such as nginx.service (got 'poweroff.target'); targets, slices, sockets and other unit types are refused
$ hc-approve web-01 patch.packages packages=openssh-server-
hc-approve: package 'openssh-server-' is refused: a name starts with a letter or digit, doesn't end in -, + or = (apt reads those as remove, install or version) and has none of * ? [ ] ^ $ / @ % ~
A hostile client can skip hc-approve, so the gate checks everything again. HostCrust ran this build on Debian 12 and AlmaLinux 9.8 test servers, both called web-01 here, on 14 Nov 2026 (UTC). “Hand-signed” means a valid signature that skipped hc-approve's checks.
| Request | Debian 12 | AlmaLinux 9.8 |
|---|---|---|
Shell text (id;), a terminal, or a restart with no approval | Refused or needs_approval; nothing ran | Not repeated |
| Signed restart of a running service | Ran; verified active | Ran; verified active |
| The same approval again | Refused | Refused |
| A unit that was never started | Refused; approval unused | Same |
debug-shell.service (a root shell), hand-signed | Refused by name | Same |
| sshd under other names and aliases | Refused; sshd PID unchanged | Same |
| Package-name tricks, hand-signed | Refused: openssh-server-, tzdata=, tzdat., tzdata:i386 | Refused: openssh-server-, @core, tzdata.noarch, tzdat |
| Empty or corrupt nonce store | Every approval refused | Same |
| Client killed mid-restart | Finished; all four receipts written | Same |
ssh-mcp-guard-verify over the whole log | OK, 104 receipts | OK, 92 receipts |
Two results to know. On Debian, tzdata:all passed the exact-name check and was upgraded, which matches the documented rule. And rc-local.service was failed on both images, so a signed restart of it would run /etc/rc.local again as root. Read the unit name before you sign.
What can an agent running as you still do?
hc-gate controls the agent's key on the server, not your laptop. Your approver key, hosts.ini, hc-approve and your shell's startup files belong to your OS user, and an agent running as you with no sandbox can reach them:
- An approver key with no passphrase, or one unlocked in ssh-agent, lets the agent sign any approval itself. hc-approve warns about an unprotected key.
- It can answer the prompt. hc-approve reads “yes” from the terminal, which stops a pipe but not a program that opens a pseudo-terminal. In HostCrust's second review, on 14 Nov 2026 (UTC), one got a signed
system.rebootapproval with no person involved. That's still possible in 0.9.0; see the next point for what stops it. - With a passphrase or a FIDO key, it can't sign without you, but it can change what you sign or capture the passphrase: edit
hosts.ini, patch or alias hc-approve, or plant a fakessh-keygen. Read the screen. - It can use your own keys. The gate guards one key; with your admin key or ssh-agent, the agent logs in as you.
- Server output can steer it. It's labeled untrusted, but the model still reads it. Read-only actions can also read admins'
sudolines in the journal; setdiag.journal = approvalif that matters.
What it can't do, with any key: run an action the policy doesn't allow, run a change without a valid signature from a key in allowed_signers, reuse an approval, use one on a server with a different id, or change the signed parameters.
What keeps approvals yours: run the agent as another OS user, or in a container or VM that can't read your home directory, or approve on another device.
Known gaps in 0.9.0
HostCrust reviewed ssh-mcp-guard twice itself, both times on 14 Nov 2026 (UTC), and fixed the high and medium findings. SECURITY.md lists what's still open:
- The receipt log can be restarted unnoticed: replace its directory and a new chain starts at seq 1. Only a head hash kept off the server shows it.
- Approvals are bound to the server id only, so a server image cloned after
hc-gate installshares it, and one approval could run once on each copy. An approval valid longer than the policy allows is refused at first but accepted near the end of its life. - Restarts use a never-restart list, not an allowlist. A database, say, isn't on it, so it can be restarted with an approval.
- A patch that times out after 30 minutes is killed, which can leave dpkg half-configured;
dpkg --configure -arecovers. - ssh-mcp-guard-verify is lenient about duplicate keys and non-canonical lines, and crashes on one kind of malformed escape.
- hc-gate runs entirely as root and isn't started with
python3 -I. On Debian, the client's locale settings reached it.
How does ssh-mcp-guard compare with other SSH MCP servers?
We haven't tested other SSH MCP servers. This comes from each project's README, read on 15 Nov 2026, and covers where each kind of check runs; a full ranking is linked under Related.
| Approach | Where the check runs | If the agent runs ssh itself | Examples |
|---|---|---|---|
| No command policy | Nowhere | Nothing to skip | classfang/ssh-mcp-server without --whitelist |
| Allowlists or approval prompts in the MCP server | On your machine | The check never sees it | tufantunc/ssh-mcp; bvisible/mcp-ssh-manager |
| Agent permission rules and hooks | On your machine | Text matching can be sidestepped | Claude Code's rules and hooks; dcg |
| Forced command | sshd, on the server | Reaches the same gate | command= by hand; sshdo; ssh-mcp-guard |
Where the others do more: tufantunc/ssh-mcp runs any command its policy allows, classifying each by its arguments, with roles, MCP approval prompts and an optional hash-chained audit log (off by default). mcp-ssh-manager has a desktop app, a credential vault, many more tools and its own guard hook. classfang/ssh-mcp-server transfers files. sshdo learns an allowlist from real use. ssh-mcp-guard has 11 fixed actions, no file transfer, and supports only Linux with systemd.
Compared with client-side approval prompts, the difference is where “no” is enforced. A prompt decides whether one tool call goes ahead; hc-gate decides whether the server runs anything for that key. Use both. The forced-command idea isn't new; sshdo and an Ask HN thread got there first.
Requirements
| Server (hc-gate) | Laptop | |
|---|---|---|
| System | Linux with systemd and apt, dnf or yum | macOS or Linux |
| Python | 3.6+, standard library only | 3.10+, plus pipx |
| OpenSSH | 8.1+, to verify approvals | 8.1+, to sign them |
AlmaLinux and Rocky Linux 8 are read-only and untested: their OpenSSH 8.0 can't verify approvals, so hc-gate refuses them. SELinux enforcing and FIDO approver keys are untested too.
Changelog
- 0.9.0 (pre-release): first release, kept below 1.0 until an outside security review. Fixes from HostCrust's own reviews: restarts limited to running or failed
.serviceunits off the never-restart list; exact package names, with apt's--no-remove; server output marked untrusted; a harder-to-fake approval screen; receipts for every request; a crash-safe nonce store.
How we checked this: ssh-mcp-guard 0.9.0 (commit 3b21a20): its 133 unit tests on macOS 14 with Python 3.14.7 on 14 Nov 2026 (UTC), and hc-approve and the bundled ssh-mcp-guard-verify run from the source tree on the same Mac with throwaway keys and the sample receipts in docs/receipts.md. Every laptop output block on this page is copied from those runs, except the approval screen, which comes from the same test of commit b988a52 (hc-approve hasn't changed since), with one key path shortened. The server results come from HostCrust's end-to-end run of commit b988a52, which differs from 3b21a20 only in the verifier's name, on 14 Nov 2026 (UTC) on two test servers, Debian 12 (OpenSSH 9.2p1, sudo 1.9.13p3, systemd 252) and AlmaLinux 9.8 (OpenSSH 9.9p1, sudo 1.9.17p2, systemd 252, SELinux disabled), following the README's install steps; an earlier 0.9.0 build ran on Ubuntu 24.04. Not tested: AlmaLinux or Rocky Linux 8, SELinux enforcing, a FIDO approver key, and the setup inside Claude Code, Codex or Cursor (the MCP server was driven over stdio directly). The comparison with other tools comes from their own documentation, read on 15 Nov 2026, not from tests. Anything we didn't run ourselves comes from the official documentation listed under Sources.
Check which CVEs are really open on your server
HostCrust Patch Proof compares every installed package with your distribution's own security data. It counts fixes your distro backported and checks the kernel that is actually running, not just the one on disk. Read-only, no root, free.
FAQ
Can Claude Code bypass an SSH MCP server's restrictions?
Yes, if the restrictions live only in the MCP server, a hook or Claude Code's permission rules, and the agent can run shell commands with a usable SSH key: it can run ssh itself. With ssh-mcp-guard, sshd on the server restricts the agent's key, so plain ssh with it reaches the same gate. A different key, such as yours in ssh-agent, still gets around it, so keep yours out of the agent's reach.
What are the MCP server security best practices for SSH access?
Restrict the agent's own SSH key on the server, not only in the client. Default to read-only. Make each change need an approval the server checks, bound to one server, one action and one use. Keep an audit log you can verify, keep your own keys away from the agent, treat server output as untrusted, and run the agent as another OS user or in a sandbox.
Is ssh-mcp-guard safe to use on production servers?
Go slowly. 0.9.0 is a pre-release without an outside security review; HostCrust reviewed it twice itself and lists the open gaps in SECURITY.md. Start with the read-only policy (examples/policy-readonly.ini) on servers that matter, and allow approved changes once you've watched it work.
Does ssh-mcp-guard work on AlmaLinux 8 or Rocky Linux 8?
Only with the read-only policy, and it's untested there. Both ship OpenSSH 8.0, whose ssh-keygen can't verify signatures (-Y arrived in 8.1), so hc-gate refuses every approval.
Sources
- ssh-mcp-guard README: install, Claude Code, Codex and Cursor setup, actions, limits
- ssh-mcp-guard SECURITY.md: threat model, review findings and known gaps
- ssh-mcp-guard docs/receipts.md: receipt format, hash rule and a sample chain
- ssh-mcp-guard Claude Code hook: claude-code-deny-raw-ssh.py
- sshd(8) manual: authorized_keys command= (SSH_ORIGINAL_COMMAND) and restrict
- ssh-keygen(1) manual: -Y sign, -Y verify, namespaces and allowed signers
- OpenSSH 8.1 release notes (2019): ssh-keygen gains signing and verification
- Claude Code documentation: hooks (PreToolUse, deny decisions, limits)
- Claude Code documentation: connecting MCP servers (claude mcp add, scopes)
- mfyz: Claude Code's allowlist has a blind spot (command substitution, February 2026)
- bvisible/mcp-ssh-manager README: security modes, approvals, keeping the agent on the tools
- tufantunc/ssh-mcp README: command classification, approvals, audit options
- classfang/ssh-mcp-server README: --whitelist and --blacklist
- raforg/sshdo: a forced-command allowlist for SSH keys
- Dicklesworthstone/destructive_command_guard (dcg): a command-blocking hook for coding agents (README, “Inherent Limitations”: a determined attacker can bypass it; scripts aren't inspected)
- Ask HN: How do you safely give LLMs SSH/DB access? (the command= suggestion)
- HostCrust Patch Proof: the read-only inventory collector hc-gate embeds