Overview

MCP SSH is a lightweight SSH agent designed to centralize SSH connection management for Model Context Protocol (MCP) server environments. It provides a local agent that brokers SSH sessions, enforces access policies, and records connections for auditing—so teams can manage access centrally without relying on ad-hoc key distribution or per-host configuration drift.

The agent runs next to a developer or automation process, talks to an MCP control plane to fetch policies and ephemeral credentials, and exposes a standard SSH integration point (SSH_AUTH_SOCK / ProxyCommand). This makes it easy to adopt in existing SSH workflows while adding centralized policy enforcement and connection auditing across your environment.

Features

Centralized session brokering for MCP-managed servers
Policy-driven access control (roles, TTLs, host filters)
Ephemeral credential issuance and automatic rotation
Connection auditing and tamper-evident logs
Standard SSH integration via SSH_AUTH_SOCK and ProxyCommand
Lightweight binary; runs as user agent, system service, or container
Optional metrics and health endpoints for monitoring

Installation / Configuration

Prerequisites: Go toolchain (optional), or download pre-built binary from releases.

Install from source (Go 1.18+):

# install the latest released binary
go install github.com/AiondaDotCom/mcp-ssh@latest

# or clone and build locally
git clone https://github.com/AiondaDotCom/mcp-ssh.git
cd mcp-ssh
make build

Basic configuration (config.yaml):

# example config.yaml
mcp:
  server: "https://mcp.example.com"
  api_key: "REDACTED"        # or use env var MCP_API_KEY
agent:
  listen_socket: "/run/user/1000/mcp-ssh.sock"
  cache_dir: "~/.cache/mcp-ssh"
  session_ttl: "1h"
audit:
  enabled: true
  logfile: "~/.local/share/mcp-ssh/audit.log"
metrics:
  enabled: true
  bind: "127.0.0.1:9090"

Start the agent (foreground):

mcp-ssh agent --config ~/.config/mcp-ssh/config.yaml

Run as a systemd user service (example):

# ~/.config/systemd/user/mcp-ssh.service
[Unit]
Description=MCP SSH Agent

[Service]
ExecStart=/usr/local/bin/mcp-ssh agent --config %h/.config/mcp-ssh/config.yaml
Restart=always

[Install]
WantedBy=default.target

Enable and start:

systemctl --user enable --now mcp-ssh.service

Export SSH_AUTH_SOCK to use the agent in your shell:

export SSH_AUTH_SOCK=/run/user/1000/mcp-ssh.sock
ssh-add -l    # lists keys provided by the agent (if applicable)

ProxyCommand integration (alternate mode):

# ~/.ssh/config
Host *.internal.example.com
  ProxyCommand /usr/local/bin/mcp-ssh proxy --target %h:%p

Configuration Reference

Key	Type	Default	Description
mcp.server	string	—	URL of the MCP control plane
mcp.api_key	string	—	API key or token
agent.listen_socket	string	/tmp/mcp-ssh.sock	Path to agent UNIX socket (SSH_AUTH_SOCK)
agent.cache_dir	string	~/.cache/mcp-ssh	Local cache for credentials
agent.session_ttl	duration	1h	Requested TTL for ephemeral sessions
audit.enabled	bool	false	Enable audit logging
audit.logfile	string	~/.local/share/mcp-ssh/audit.log	Audit log path
metrics.enabled	bool	false	Enable metrics endpoint
metrics.bind	string	127.0.0.1:9090	Metrics bind address

Available Tools / Resources

CLI binary: mcp-ssh — main agent and helper subcommands (agent, proxy, register, audit)
Systemd unit example for user or system services
Docker image: run agent in containerized environments (useful for CI runners)
Audit logs: JSON lines with session metadata (user, target, start/end, policy applied)
Metrics endpoint: Prometheus-style metrics for session counts, errors, and latencies
Documentation and examples in the repository README and examples/ directory

Use Cases

Centralized developer access to ephemeral environments
- Developers run the agent locally and authenticate to MCP. The agent issues short-lived credentials on demand so access is revoked automatically after TTL expiry.
- Example: connect to a CI-created host without sharing long-lived keys.
Bastion host session brokering with audit trails
- Replace ad‑hoc bastion key distribution with the agent acting as a proxy. All sessions are recorded into a centralized audit log for compliance.
- Example: set ProxyCommand to call mcp-ssh proxy and review audit logs for session review.
Automated jobs and CI runners
- CI runners use the agent in a container to fetch ephemeral access for deployment targets. Policies limit which targets the runner can reach and for how long.
- Example: a deploy job invokes mcp-ssh to obtain credentials scoped to a single deployment window.
Role-based host access for contractors and rotating teams
- Grant contractors temporary access by issuing short-lived tokens via the MCP control plane; the agent enforces role membership and host filters.
- Example: issue a token that only allows access to staging machines for 4 hours.

Notes and Best Practices

Keep MCP API credentials out of version control; prefer environment variables or secure secret stores.
Use systemd user services for per-developer agents so SSH_AUTH_SOCK is managed automatically.
Enable audit logging and ship logs to centralized storage for long-term retention and compliance.
Monitor the metrics endpoint to track agent health and connection patterns.

For full command reference, examples, and deployment templates, consult the repository’s examples directory and the included

SSH Agent for MCP Server Connection Management