How to Configure Claude Code SSH MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a claude code ssh mcp server by registering an MCP tool with host keys. The agent then uses the Model Context Protocol to run commands on remote machines. Engineering teams often set up this workflow with a shared SSH key on developer laptops. When host roles or user permissions are too broad, the agent can change live system files. How a claude code ssh mcp server works Claude Code reaches external tools and systems through the Model Context Protocol. The vendor docs state that MC

Claude Code Security + SSH Bastion Hosts / Jump Servers: the complete guide

Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.

Free white paper. No spam. Unsubscribe anytime.

You set up a claude code ssh mcp server by registering an MCP tool with host keys. The agent then uses the Model Context Protocol to run commands on remote machines. Engineering teams often set up this workflow with a shared SSH key on developer laptops. When host roles or user permissions are too broad, the agent can change live system files.

How a claude code ssh mcp server works

Claude Code reaches external tools and systems through the Model Context Protocol. The vendor docs state that MCP servers give the agent reach into tools, databases, and APIs. You can also run remote shell commands through its built-in Bash tool. In Manual mode, the Bash tool asks for approval before it runs most commands. A small built-in list of read-only commands runs without a prompt. When you add an MCP server for SSH, the local MCP process opens the remote session. It reads your local SSH setup and uses private keys or signed certificates to log in.

Many teams use OpenSSH certificates instead of static keys for host logins. OpenSSH added certificate logins for users and hosts in version 5.4. A certificate holds a public key, identity data, principal names, and options signed by a CA key. This format is much simpler than the X.509 format used in TLS. You sign a public key with a CA key to make a user certificate. You also set a key identity and list one or more user or host principals. If you do not set a time limit, the certificate stays valid forever.

Preparing host roles and user keys

Before you link the agent to a remote machine, you must lock down the Linux user. Do not give the MCP tool a root key or a user with full sudo rights. Create a dedicated user account on the target host for the agent. Give that account read-only rights to log folders and app files. The official Claude Code docs give similar advice for database links. They tell readers to use a read-only user so queries cannot change data.

You should also check the code of the MCP tool itself. The vendor docs warn you to verify that you trust each server before you use it. A local MCP process runs with your own laptop user permissions. It can read local keys, environment variables, and config files on your disk. Store private keys with strict file permissions so other local processes cannot read them. If you use OpenSSH certificates, set a short time window when you sign the key.

Claude Code Security + SSH Bastion Hosts / Jump Servers: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native SSH setup solves and what it misses

Native OpenSSH keys and Linux accounts solve the basic login problem. They verify who can open a session on a remote host. Host firewalls and bastion hosts also limit which networks can reach the server. Dedicated Linux users stop the agent from writing to protected system folders. These native controls form a strong base for host security.

Still, host login controls only decide who gets into the machine. Once the session starts, the SSH daemon does not check each command in flight. An agent with shell access can still run heavy scripts that spike CPU usage. It can also read sensitive files that belong to its own Linux user. If a log file holds emails, phone numbers, card numbers, or national IDs, the output includes them. Standard SSH setups cannot rewrite matched fields in results before they reach the AI model. Also, local MCP approvals happen on the developer laptop, not on a central server. Security teams do not get a central log of every command the agent ran across hosts.

Add command and file guardrails to SSH access

Host firewalls and certificate principals control who opens an SSH session. Yet an allowed user or agent can still run a bad one-shot command or pull sensitive files over sftp. In practice, hoop.dev sits inline on the host as an open-source SSH server with guardrails that uses OpenSSH certificates. For every one-shot command or sftp task an agent or human runs in production, hoop.dev decides to pass, mask, block, or escalate it for review.

Using hoop.dev SSH controls, guardrails check one-shot commands, env variable names, and sftp or scp paths before they run. Port forwards default to deny unless the target is listed. Because interactive shells have no statement boundary and carry no guardrails, teams can turn them off so every command is checked and logged. Check out the MIT-licensed project on GitHub.

Frequently asked questions

How does Claude Code run commands on an SSH host?

It connects through a configured MCP server for SSH or runs SSH via its Bash tool. Both methods use the keys and config files stored on the user machine.

Does the agent ask before it runs shell commands?

In Manual mode, the built-in Bash tool asks for approval before running most commands. Still, calls made through a third-party MCP server follow that server's own rules and tool definitions.

How can we limit what the agent does on a remote Linux host?

Create a restricted Linux user without sudo rights and use short-lived OpenSSH user certificates. For deeper control, inspect individual commands and mask sensitive output in flight.

Save the open-source gateway.

hoop is MIT-licensed infrastructure for controlling how AI agents reach production data. Star hoophq/hoop so you can inspect it, deploy it, or share it when your team starts governing agent access.