Why we built it

An agent on prod is a trust problem before it’s a tooling problem

Hand an AI agent raw SSH and you’ve handed it standing access to your infrastructure — no scope, no allowlist, no record of what it touched. SSH-MCP puts a boundary between the agent and the host: every action is requested, evaluated and audited before anything reaches a shell. The agent operates on a leash, not on trust.

The handshake

Four steps, every single call

The agent never talks to the host directly. It talks to the boundary — and the boundary talks to the host.

01 · REQUEST

Agent calls a tool

It asks for create_ssh_session, execute_remote_command or smart_file_edit. Nothing runs yet.

02 · EVALUATE

Boundary checks scope

Identity and scope are verified, the command is matched against an allowlist, and writes require a diff preview.

03 · EXECUTE

Only allowed actions run

Permitted calls reach the host inside a tracked, short-lived session — never a persistent door.

04 · REAP

Return & clean up

Output flows back, the session is closed after 30s idle, and every step — allowed or denied — is logged.

What makes it safe

A slim surface, deliberately

Version 2.0 cut the server from 93 tools to 13 essentials — a 86% reduction that traded sprawl for reliability. The codebase shrank from ~6,200 lines to ~1,700, and the build from 222KB to 140KB.

The policy guard

Every request is checked against identity, scope and an allowlist before it executes. Destructive patterns are refused outright — a denied rm -rf never reaches the shell, and it’s logged exactly like a successful deploy.

30-second idle reaper

Idle SSH connections are how you end up with zombie processes and forgotten access. SSH-MCP closes sessions aggressively, so open doors trend toward zero.

Diff-previewed writes

smart_file_edit runs in three modes — simple search/replace, VIM ex-commands or sed scripts — with automatic backups, syntax validation and a dry-run preview.

Full audit trail

Every request — allowed or denied — is logged with identity, scope and outcome. That trail is what a security team signs off on.

Scoped sessions & live metrics

A session is a short-lived grant carrying an identity, a scope (read / exec / write) and a host set — with adaptive connection pooling, per-host limits and real-time pool, performance and security metrics exposed.

The surface

Thirteen essential tools

Sessions, remote exec, SFTP and smart file-editing — each behind the policy guard.

Tool	What it does
Session management
`quick_connect`	Connect to a predefined server from `.env`.
`create_ssh_session`	Open a custom SSH session with full configuration.
`list_sessions`	List all active SSH sessions.
`close_session`	Close a session and reclaim its resources.
`list_predefined_servers`	List every server available from `.env`.
`check_device_availability`	Check a host is reachable before connecting.
Execution & files
`execute_remote_command`	Run a shell command on the remote host.
`transfer_file`	Upload / download files over SFTP.
`smart_file_edit`	Edit files in 3 modes — simple, VIM ex, or sed — with backup, syntax-check and dry-run.
`create_or_update_sitemap`	Generate `sitemap.xml` for a website root.
Monitoring & analytics
`get_performance_metrics`	Real-time connection-pool performance and recommendations.
`get_pool_statistics`	Detailed connection-pool statistics.
`get_security_metrics`	Failed authentications and threat signals.

Wire it up

Built on TypeScript 5.7 & the MCP SDK

Runs on Node.js 20+. Configuration is environment-variable only — no sprawling config files. Register it with any MCP client and your agent discovers the guarded surface.

~/.claude.json · mcpServers

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"],
      "env": { "SSH_MAX_IDLE_TIME": "30000" }
    }
  }
}

agent prompt

# Ask the agent in plain language:
Connect to the prod server and show me nginx status.

# Under the hood, on a leash:
quick_connect(prod) → execute_remote_command("systemctl status nginx")
# guard checks scope · runs · returns output · reaps the session

Read the full setup guide → · How the boundary works →

We build in the open

Read it, run it, fork it

SSH-MCP is the flagship of our open-source agentic-infrastructure toolchain — the same boundary we deploy and harden for client teams running agents against real infrastructure.

SSH-MCP

A slim, production MCP server giving agents 13 guarded SSH capabilities, a 30-second idle reaper and full audit logging.

git.churchofmalware.org/Trilltechnician/ssh-mcp

Open Source TypeScript 5.7 MCP 0.6.0 · Node 20+ MIT License

Browse the repo ↗