How to Configure OpenHands SSH MCP Server
You set up an openhands ssh mcp server by linking your agent to an SSH tool runner. Next, you give that runner a valid SSH key or certificate for your target host. Most teams start by mounting a static private key inside the agent container. That quick setup lets the agent log in, but broad host permissions create big risks. One bad prompt can wipe files, change system rules, or read sensitive data. How the openhands ssh mcp server workflow operates OpenHands uses the Model Context Protocol t
SSH Bastion Hosts / Jump Servers + Kubernetes API Server Access: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up an openhands ssh mcp server by linking your agent to an SSH tool runner. Next, you give that runner a valid SSH key or certificate for your target host. Most teams start by mounting a static private key inside the agent container. That quick setup lets the agent log in, but broad host permissions create big risks. One bad prompt can wipe files, change system rules, or read sensitive data.
How the openhands ssh mcp server workflow operates
OpenHands uses the Model Context Protocol to run shell commands on remote Linux machines. The agent decides what command it needs and sends a request to the MCP server. The MCP server opens an SSH session to the target host and runs the command. Then it sends the text output back to the agent so the task can continue.
To log in, the server needs an SSH key pair or an OpenSSH certificate. OpenSSH certificates are much simpler than X.509 certificates and arrived in OpenSSH 5.4. A Certification Authority key signs the user key and attaches an identity string. The signed certificate also holds a list of allowed principal names and key options. When you sign a key without a time limit, the certificate stays valid forever. Teams should always set a short validity window when signing keys for an agent.
What native SSH setup solves and what it misses
Native OpenSSH keys and certificates do a great job checking who can log in. They verify that the MCP server holds a trusted key for a specific Linux user. You can also use a jump host to keep remote machines off the public internet. This setup stops outside attackers from reaching your private hosts directly.
Still, native SSH setup stops working the moment the session starts. Once the agent logs in as a Linux user, it gets every permission that user has. Standard SSH does not check individual shell commands while they run in flight. If the agent runs a dangerous delete command, the remote host will execute it right away. If a command prints database rows, raw emails and phone numbers go straight to the model. Static keys sitting on disk are also easy for a confused agent to read and leak.
SSH Bastion Hosts / Jump Servers + Kubernetes API Server Access: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Securing agent sessions on remote hosts
Running an AI agent over SSH requires tight controls on both login and command execution. Start by giving the agent a dedicated Linux user with minimal file permissions. Never let an automated agent log in as the root user or share admin keys. Use OpenSSH user certificates with short lifetimes instead of permanent private keys on disk.
You should also separate safe read commands from risky write commands. An agent checking disk space or reading app logs does not need write rights. When the agent needs to restart a service or edit a file, require human review first. Finally, check all command output for sensitive text like card numbers or national IDs. Masking rewrites matched fields in results before the text reaches the model context.
Check SSH commands and file transfers on the host
OpenSSH keys and certificates decide who can log into a Linux host. They do not check what a one-shot command or file transfer does once the session starts. With hoop.dev, you run an open-source SSH server with guardrails on the host. It checks callers with OpenSSH certificates and works with ssh, sftp, scp, and rsync clients.
When a caller runs a one-shot command or moves a file, hoop.dev guardrails check the command or path before it runs. Then hoop.dev data masking masks matched sensitive patterns in downloads and output. Interactive shells carry no guardrails because keystrokes have no statement boundary. Teams can turn interactive shells off and allow only commands and file tasks. The audit trail logs who connected and what was allowed or refused, without storing keystrokes or file bytes. See the source on GitHub.
Frequently asked questions
How does OpenHands talk to remote servers over MCP?
OpenHands sends tool calls to the local MCP server process. That process opens a standard SSH session, runs the shell command, and returns the output.
Should I use static SSH keys or OpenSSH certificates for agents?
OpenSSH certificates are much safer because you can set a short expiration window. Static keys stay valid until someone removes them from the remote server.
Why is a restricted Linux user not enough for AI agents?
A Linux user still allows any command within its file permissions to run without review. It also does not mask emails or phone numbers in command output.
Related guides
In this post