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

View on GitHub

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

Updated November 15, 2026By HostCrust

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-gate runs 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-guard is the local MCP server. Read-only actions run straight away; changes wait for you.
  • hc-approve shows exactly what a change will run, then signs it with your SSH key.
  • ssh-mcp-guard-verify checks the server's receipt log offline, recomputing its SHA-256 hash chain with the rule written out in docs/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 ssh itself 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?

How ssh-mcp-guard handles a request from an AI agent On the laptop, the AI agent calls the ssh-mcp-guard MCP server, or runs plain ssh, with the agent's key. Either way, the server's sshd runs hc-gate, the key's forced command. hc-gate checks the action against policy.ini. A read action runs at once. A change needs an approval you signed in hc-approve with ssh-keygen -Y sign; hc-gate verifies the signer, the server id, the expiry and an unused nonce, or runs nothing. Actions run as fixed commands with no shell, and the result is checked. Every request is written to a hash-chained receipt log, which ssh-mcp-guard-verify checks offline on the laptop. Your laptop: the agent runs here Server web-01: root decides AI agent Claude Code, Codex or Cursor tool call ssh-mcp-guard local MCP server (stdio) You, in your own terminal hc-approve shows exactly what will run, then signs ssh-keygen -Y sign signed approval submit_approved ssh-mcp-guard-verify checks the chain offline or plain ssh, same key ssh with the agent's key sshd runs the key's forced command command="sudo -n hc-gate",restrict hc-gate checks policy.ini named actions only, never a shell Read action status, logs, units runs at once Change restart, patch, reboot needs a signed approval Run, then verify fixed argument lists, never a shell; then check the result ssh-keygen -Y verify key in allowed_signers this server's id, in time nonce never used if not: nothing runs valid /var/log/hc-gate/receipts.jsonl every request, refused or not, hash-chained get_receipts
Plain 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:

ActionWhat it doesDefault
diag.status, diag.topUptime, memory, disk, failed units, top processeson
diag.journal, diag.serviceUp to 200 journal lines, or systemctl status, for one uniton
inventory.collect, gate.receiptsThe Patch Proof package inventory; the receipt logon
service.restartRestart one running or failed .service unit, then check itapproval
patch.packages, patch.allUpgrade named packages, or all, with apt, dnf or yumapproval
system.rebootSchedule a rebootapproval
shell.runAny command, through /bin/shoff

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.

RequestDebian 12AlmaLinux 9.8
Shell text (id;), a terminal, or a restart with no approvalRefused or needs_approval; nothing ranNot repeated
Signed restart of a running serviceRan; verified activeRan; verified active
The same approval againRefusedRefused
A unit that was never startedRefused; approval unusedSame
debug-shell.service (a root shell), hand-signedRefused by nameSame
sshd under other names and aliasesRefused; sshd PID unchangedSame
Package-name tricks, hand-signedRefused: openssh-server-, tzdata=, tzdat., tzdata:i386Refused: openssh-server-, @core, tzdata.noarch, tzdat
Empty or corrupt nonce storeEvery approval refusedSame
Client killed mid-restartFinished; all four receipts writtenSame
ssh-mcp-guard-verify over the whole logOK, 104 receiptsOK, 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.reboot approval 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 fake ssh-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' sudo lines in the journal; set diag.journal = approval if 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 install shares 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 -a recovers.
  • 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.

ApproachWhere the check runsIf the agent runs ssh itselfExamples
No command policyNowhereNothing to skipclassfang/ssh-mcp-server without --whitelist
Allowlists or approval prompts in the MCP serverOn your machineThe check never sees ittufantunc/ssh-mcp; bvisible/mcp-ssh-manager
Agent permission rules and hooksOn your machineText matching can be sidesteppedClaude Code's rules and hooks; dcg
Forced commandsshd, on the serverReaches the same gatecommand= 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
SystemLinux with systemd and apt, dnf or yummacOS or Linux
Python3.6+, standard library only3.10+, plus pipx
OpenSSH8.1+, to verify approvals8.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 .service units 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.

Run the free check About Patch Proof

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

  1. ssh-mcp-guard README: install, Claude Code, Codex and Cursor setup, actions, limits
  2. ssh-mcp-guard SECURITY.md: threat model, review findings and known gaps
  3. ssh-mcp-guard docs/receipts.md: receipt format, hash rule and a sample chain
  4. ssh-mcp-guard Claude Code hook: claude-code-deny-raw-ssh.py
  5. sshd(8) manual: authorized_keys command= (SSH_ORIGINAL_COMMAND) and restrict
  6. ssh-keygen(1) manual: -Y sign, -Y verify, namespaces and allowed signers
  7. OpenSSH 8.1 release notes (2019): ssh-keygen gains signing and verification
  8. Claude Code documentation: hooks (PreToolUse, deny decisions, limits)
  9. Claude Code documentation: connecting MCP servers (claude mcp add, scopes)
  10. mfyz: Claude Code's allowlist has a blind spot (command substitution, February 2026)
  11. bvisible/mcp-ssh-manager README: security modes, approvals, keeping the agent on the tools
  12. tufantunc/ssh-mcp README: command classification, approvals, audit options
  13. classfang/ssh-mcp-server README: --whitelist and --blacklist
  14. raforg/sshdo: a forced-command allowlist for SSH keys
  15. 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)
  16. Ask HN: How do you safely give LLMs SSH/DB access? (the command= suggestion)
  17. HostCrust Patch Proof: the read-only inventory collector hc-gate embeds