synapse-rmcp

MCP server and CLI for host and container operations: Docker and Compose control, SSH, host inspection, logs, ZFS, and safe file transfer.

Synapse is a full-parity Rust port of synapse-mcp, built with the rmcp framework.

The server exposes two MCP tools (flux and scout) plus equivalent CLI commands, covering all 59 production actions from the original TypeScript server.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Plugin Packages
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Authentication
• Safety And Trust Model
• Distribution Contract
• Verification
• Deployment
• Troubleshooting
• Tools and Actions
• Known Parity Gaps
• Configuration
• Run
• Architecture
• Development
• Documentation
• Related Servers
• License

Naming

The repository is synapse-rmcp, the Rust crate is synapse, the MCP server identity is synapse, and the installed binary is synapse. The npm launcher package is synapse-rmcp.

Across most of the RMCP family, naming follows repo=<service>-rmcp, npm=<service>-rmcp, and CLI=r<service>. Synapse is an exception because it is a Rust port of the older TypeScript synapse-mcp project and keeps the operator-facing synapse binary.

Capabilities And Boundaries

Synapse provides local Docker, Compose, host, SSH, log, ZFS, and file-operation workflows through two MCP tools and the equivalent CLI:

• flux manages Docker infrastructure, containers, Compose projects, and host inspection.
• scout handles SSH/local host inspection, safe file reads, allowlisted command execution, bounded descriptor-confined file transfer, ZFS introspection, and log retrieval.
• REST exists only as a compatibility shim for a subset of actions.
• The web surface is a lightweight static admin shell, not a full dashboard.

Not for: arbitrary shell access, unaudited remote mutation, or bypassing host SSH trust. Destructive Docker/Compose/exec/file-transfer actions require explicit host targets and confirmation policy.

MCP callers never provide credentials, tokens, keys, or secrets as action arguments. Tokens, OAuth settings, host topology, SSH trust, and allowlists live in server-side configuration or the local SSH environment.

Install

Use the npm launcher for stdio MCP or CLI access without a manual binary install:

npx -y synapse-rmcp --help
npx -y synapse-rmcp mcp

For a permanent command:

npm i -g synapse-rmcp
synapse --version

The npm package downloads the synapse binary from GitHub Releases during postinstall, keeping the release tag aligned with packages/synapse-rmcp/package.json.

From source:

cargo build --release

The production image includes Python 3 plus the official Docker CLI/Compose plugin because Scout's remote descriptor wrappers and Flux Compose operations invoke those runtime tools. The image does not contain a Docker daemon; Flux uses the mounted socket or SSH-forwarded remote socket. Persistent appdata lives at ~/.synapse on the host and /data in the container.

Quickstart

The first-screen 30-second path is:

npx -y synapse-rmcp mcp

Then configure an MCP client with stdio:

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-rmcp", "mcp"]
    }
  }
}

Start with a read-only call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "to