Skip to content

MCP SSH Gateway

This guide enables SSH Gateway integration through the local Dockerized mcp-ssh-gateway server registered in .mcp.json.

Scope

Current implementation in this repository provides:

  • Docker-only MCP transport
  • Pinned immutable runtime image digest
  • Pinned upstream source commit checkout
  • Bitwarden-managed SSH identity for remote command execution
  • Local static connection declarations in .data/mcp-ssh-gateway/config/connections.json

Runtime image: docker.io/python:3.12-slim

Source pin: olilanz/mcp-ssh-gateway@1303f538fb36ab45b8f2a685a30de9ff4cf7cc73

1. Initialize local SSH Gateway paths

Create a starter connection config:

just mcp-ssh-gateway-init

This creates:

  • .data/mcp-ssh-gateway/config/connections.json
  • .data/mcp-ssh-gateway/keys/

2. Generate and stash a shared SSH identity

Generate a local Ed25519 keypair:

just bw-ssh-gateway-key-generate

Push the private and public keys into Bitwarden item SSH Gateway Identity:

just bw-ssh-gateway-key-push

Install the printed public key onto remote hosts in the target user authorized_keys.

For another workstation, hydrate the same identity back from Bitwarden:

just bw-ssh-gateway-key-pull

3. Define target connections

Edit .data/mcp-ssh-gateway/config/connections.json with one object per host.

Example:

[
  {
    "name": "prod-edge-1",
    "mode": "direct",
    "user": "ops",
    "host": "10.10.10.21",
    "port": 22,
    "id_file": "/data/keys/id_ed25519"
  }
]

Use mode: "tunnel" with loopback host and reverse tunnel port when the remote initiates ssh -R to your agent host.

4. Validate MCP wiring

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

  • ssh-gateway MCP docker image: docker.io/python@sha256:<digest>

5. Example prompts

In your MCP-capable client, run prompts similar to:

Use the ssh-gateway MCP server to list configured connections.

Use the ssh-gateway MCP server to run "uname -a" on prod-edge-1.

Troubleshooting

  • Missing /data/config/connections.json: run just mcp-ssh-gateway-init.
  • Missing /data/keys/id_ed25519: run just bw-ssh-gateway-key-pull or just bw-ssh-gateway-key-generate then just bw-ssh-gateway-key-push.
  • SSH auth failures: verify the public key from .data/mcp-ssh-gateway/keys/id_ed25519.pub is installed in the correct remote user authorized_keys.
  • Connection failures: verify host, port, and network reachability from the Docker runtime.