Bridge MCP

<!-- markdownlint-disable MD033 --> <div align="center"> <img src="dxt/icon.svg" alt="Bridge MCP" width="96" height="96">

A Rust MCP server for secure remote infrastructure management — 476 tools, 9 protocols.

Claude Code  ◄──JSON-RPC──►  Bridge MCP  ◄──9 protocols──►  Your Infrastructure

</div>

---

Table of Contents

• Features
• Hero Workflows
• Quick Start
• Architecture
• Configuration
• Tool Groups
• MCP Prompts & Resources
• CLI Usage
• Daemon Mode
• Protocol Support
• Troubleshooting
• Development
• License

---

Features

• 476 tools, 77 groups — manage Linux, Windows, Docker, Kubernetes, Podman, AWX, databases, LDAP, network equipment, certificates, and more
• 9 protocol adapters — SSH, WinRM, PSRP (PowerShell Remoting), Telnet, K8s Exec, Serial, AWS SSM, Azure, GCP
• Security-first — command whitelist/blacklist, 63 secret-redaction patterns + entropy detection, tamper-proof session recording, MCP confirmation before destructive operations (on by default)
• Auto-discovery — reads ~/.ssh/config automatically, merges with YAML config
• Smart output — server-side jq_filter / yq_filter / columns / limit, TSV mode (60-80% token savings), pagination via ssh_output_fetch, per-client size limits (see Token-efficient output)
• Progressive MCP discovery — tools/list returns four meta-tools (mcp_list_tool_groups, mcp_search_tools, mcp_describe_tool to browse the registry on demand, mcp_call_tool to invoke what you found) instead of loading all 476 schemas up front
• MCP 2026-07-28 (Modern) only — server/discover opens the connection, per-request _meta carries the revision and client capabilities, notifications are opt-in via subscriptions/listen. A pre-Modern client sending initialize gets -32022 and cannot fall forward — see Protocol Support
• MCP Tasks extension — declared under capabilities.extensions as io.modelcontextprotocol/tasks, enabling polled async execution, cancellation and progress notifications for long-running operations. The SERVER decides which calls become tasks (see task_policy::LONG_RUNNING_TOOLS); 2026-07-28 removed per-tool execution.taskSupport entirely, and no tool advertises it
• CLI + MCP — all tools available as CLI commands (10-32x token savings) or via MCP JSON-RPC
• Daemon mode — Unix-socket transport for multi-client local usage; built-in WinRmPool (120 s TTL) and K8sExecPool (300 s TTL) amortize TLS handshakes across calls
• 9500+ tests — #![forbid(unsafe_code)], Rust 2024 edition, strict clippy

---

Hero Workflows

Four end-to-end recipes that show why this exists. Every command runs through one CLI binary; all 476 tools sit behind the same flag conventions (--jq, --columns, --limit, --output-format).

1. Diagnose a Linux service in 4 commands

bridge-mcp status                                       # check host reachability
bridge-mcp tool ssh_service_status host=web1 service=nginx
bridge-mcp tool ssh_service_logs   host=web1 service=nginx lines=200
bridge-mcp tool ssh_journal_query  host=web1 unit=nginx priority=err since="-1h"

Built-in validation rejects unknown hosts before any SSH bytes leave your machine; outputs are sanitized through 63 secret-redaction patterns + entropy detection.

2. Inspect Kubernetes with 80% fewer tokens

# Dump all pods → 50 KB JSON. Pipe through server-side jq → ~6 KB TSV.
bridge-mcp --jq '.items[] | [.metadata.name, .status.phase, .spec.nodeName]' \
  --output-format=tsv \
  tool ssh_k8s_get host=k8s resource=pods namespace=default

bridge-mcp tool ssh_k8s_describe host=k8s resource=pod name=api-7d-xyz namespace=default
bridge-mcp tool ssh_k8s_logs     host=k8s pod=api-7d-xyz container=app tail=100

Filtering happens server-side, before truncation — you never lose data to the output cap. Same pattern works for ssh_docker_inspect, ssh_helm_status, ssh_awx_*, etc.

3. Cross-platform: Windows + Linux from one CLI

# Linux host
bridge-mcp tool ssh_service_status   host=web1 service=postgres
# Windows host (WinRM/PSRP under the hood — no agent install on the target)
bridge-mcp tool ssh_win_service_status host=appsrv service=W3SVC
bridge-mcp tool ssh_iis_restart        host=appsrv name=DefaultAppPool
bridge-mcp tool ssh_win_event_query    host=appsrv log=System level=Error since="-1h"

13 Windows tool groups (services, events, AD, IIS, scheduled tasks, registry, Hyper-V, …) map cleanly onto the same ssh_* namespace, no protocol switch in your prompts.

4. Audited destructive ops with confirmation

# config.yaml
security:
  require_elicitation_on_destructive: true   # DEFAULT. Confirm any destructive_hint:true tool
audit:
  enabled: true
  path: /var/log/bridge-mcp/audit.log        # absolute, or ~/… (expanded to $HOME)

Session recording (tamper-proof asciinema/JSON) is driven at runtime by the ssh_recording_* tools plus the MCP_RECORDING_KEY env var — not a config section.

// Over MCP. The gate is MCP-only — see the note below the snippet.
{"method": "tools/call",
 "params": {"name": "ssh_helm_rollback",
            "arguments": {"host": "k8s", "release": "api", "revision": 7}}}

The server answers resultType: "input_required" carrying an elicitation/create request and a signed requestState; the client gathers the confirmation and RETRIES the same call under a new id with the answer attached. Nothing runs until then, and the audit log records the args, sanitized stdout, exit code and duration of the call that finally executes.

The CLI is not covered by this gate. bridge-mcp tool ssh_helm_rollback … has no client to ask and never prompts. Confirmation is an MCP-mode control; the CLI's protection is the blacklist and the audit log.

The dispatcher distinguishes read_only vs mutating vs mutating_idempotent vs destructive per tool (audited via tests/annotation_audit.rs), so confirmations only fire when state actually changes.

---

Quick Start

1. Install

# Linux x86_64 (recommended)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-x86_64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

<details> <summary>Other platforms & methods</summary>

# Linux aarch64 (Raspberry Pi, ARM servers)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-arm64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

# macOS (Apple Silicon)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-macos-arm64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

# Docker
docker pull ghcr.io/muchiny/bridge-mcp:latest

# From source
git clone https://github.com/muchiny/bridge-mcp && cd bridge-mcp && make release

Claude Desktop (DXT): download the .dxt file from Releases and drag-and-drop into Claude Desktop.

</details>

Claude Code plugin (one command). Install the plugin from the marketplace — it registers the /bridge-mcp:bridge and /bridge-mcp:discover skills, the MCP server, and a binary-bootstrap hook:

claude plugin marketplace add muchiny/bridge-mcp
claude plugin install bridge-mcp@muchiny
cargo install --git https://github.com/muchiny/bridge-mcp --features full   # the binary the plugin drives

The skills auto-trigger when you mention a remote host, Docker, Kubernetes, services, logs, ports, etc.

2. Configure

mkdir -p ~/.config/bridge-mcp
cp config/config.example.yaml ~/.config/bridge-mcp/config.yaml
chmod 600 ~/.config/bridge-mcp/config.yaml   # required — the server rejects
                                             # group/other-readable config (it may hold secrets)

The config may contain SSH keys, sudo passwords and tokens, so bridge-mcp refuses to start if config.yaml is group- or world-accessible (max 0640). A fresh cp usually lands at 0644 — run the chmod above.

Edit ~/.config/bridge-mcp/config.yaml with your hosts:

hosts:
  my-server:
    hostname: 192.168.1.100
    port: 22
    user: admin
    auth:
      type: key
      path: ~/.ssh/id_ed25519
    description: "My server"

Tip: Hosts from ~/.ssh/config are auto-discovered — you may not need to configure anything.

Recommended safe defaults — add these so Claude confirms before anything irreversible and every action is logged:

security:
  mode: standard                             # blacklist + whitelist for ssh_exec
  require_elicitation_on_destructive: true   # DEFAULT; set false to run destructive tools unconfirmed
audit:
  enabled: true
  path: ~/.local/share/bridge-mcp/audit.log  # ~ expands to $HOME; absolute paths also fine

Only the 8 core tool groups are enabled by default (secure-by-default) — opt into the rest under tool_groups (see Tool Groups; the example config ships ready-to-use K3s and Docker profiles).

3. Add to Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ssh-bridge": {
      "command": "bridge-mcp"
    }
  }
}

Your MCP host must speak MCP 2026-07-28. bridge-mcp 3.x removed the initialize handshake; a host that opens with initialize receives -32022 Unsupported protocol version and the connection is dead. If your host is not there yet, stay on v1.20.0 — the last release that speaks the Legacy handshake. There is no 2.x to fall back to: 2.0.0 through 2.2.0 were written but never tagged or published, and those numbers are burnt (see the note under the 2.2.0 heading in CHANGELOG.md). The CLI-as-tool mode (bridge-mcp tool …) is unaffected either way, because it never speaks JSON-RPC at all.

Claude Code needs one setting, or it sends the Legacy handshake. Measured on 2.1.239: it implements 2026-07-28 fully, but defaults stdio servers to the Legacy path, so it opens with initialize and sees ZERO tools. Turn negotiation on:

{ "env": { "MCP_PROTOCOL_NEGOTIATION": "auto" } }

in .claude/settings.json (or settings.local.json), then restart. Verify with claude mcp list — the server should read ✔ Connected. Check your own client's behaviour before assuming; the symptom of getting this wrong is an empty tool list, not an error message.

4. Verify

Restart Claude Code, then ask: "Check the health of my-server" — or run:

bridge-mcp status

---

Architecture

Bridge MCP sits between Claude Code and your infrastructure. It routes commands through 9 protocol adapters with built-in security validation, output sanitization, and audit logging.

graph LR
    CC[MCP client<br/>Claude Code · Claude Desktop · scripts]
    CC -->|JSON-RPC over stdio,<br/>Unix socket or HTTP| BR[Bridge MCP]

    BR --> VAL[Validator<br/>blacklist · whitelist · confirmation gate]
    VAL --> ER[Executor Router]