synapse-rmcp

Host, Docker, Compose, SSH, logs, ZFS, and file operations over MCP and CLI.

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 @dinglebear/synapse --help
npx -y @dinglebear/synapse mcp

For a permanent command:

npm i -g @dinglebear/synapse
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 @dinglebear/synapse 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": "tools/call",
  "params": {
    "name": "scout",
    "arguments": {
      "action": "nodes"
    }
  }
}

Client Configuration

stdio is preferred for local MCP clients:

{
  "mcpServers": {
    "synapse": {
      "command": "synapse",
      "args": ["mcp"]
    }
  }
}

Streamable HTTP uses /mcp on the configured host and port:

{
  "mcpServers": {
    "synapse": {
      "url": "http://127.0.0.1:40080/mcp",
      "headers": {
        "Authorization": "Bearer ${SYNAPSE_MCP_TOKEN}"
      }
    }
  }
}

Plugin Packages

plugins/synapse/ ships Claude Code, Codex, and Gemini CLI manifests that all point at the same HTTP MCP endpoint and the same shared skill.

These packages contain no lifecycle hooks. Connecting to a server that is already running needs no setup — the manifests substitute your server_url and api_token directly. If this machine also runs the server, bootstrap it once by hand:

synapse setup install                  # put/refresh the binary on PATH
synapse setup plugin-hook              # check, then repair on blocking failures
synapse setup plugin-hook --no-repair  # audit only; never mutates appdata

Export the relevant SYNAPSE_* variables (or write them to ~/.synapse/.env) first; plugins/README.md maps each plugin option to its variable. Re-run synapse setup install after a plugin update.

Runtime Surfaces

MCP Tool Reference

Synapse exposes two MCP tools:

• flux: Docker daemon, container, host, and Compose operations.
• scout: SSH/local host inspection, filesystem reads, allowlisted exec, multi-host emit, file beam, ZFS, and logs.

Both tools use an action-dispatched JSON shape:

{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"scout","arguments":{"action":"nodes"}}

The detailed action tables below are curated README reference material. The generated runtime MCP schema and the Rust action definitions are the source of truth for the live tool contract.

CLI Reference

Common commands:

synapse flux docker info
synapse flux container list
synapse flux compose list --host myhost
synapse scout nodes
synapse scout exec --host myhost --command hostname
synapse scout zfs pools --host myhost
synapse scout logs journal --host myhost --unit docker

Authentication

Mounted HTTP supports bearer and Google OAuth modes. Loopback stdio/local dev can run without mounted HTTP auth. Important variables:

SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
SYNAPSE_MCP_AUTH_MODE=bearer

See Configuration and docs/CONFIG.md for the full auth matrix.

Safety And Trust Model

Synapse separates read and write scopes (synapse:read, synapse:write) and uses confirmation gates for destructive operations. SYNAPSE_MCP_ALLOW_DESTRUCTIVE can skip prompts only in loopback-safe contexts. Host protocol is authoritative and defaults to SSH when omitted; local execution requires the explicit built-in local host or protocol: "local". SSH host trust is delegated to OpenSSH known-hosts behavior, and command execution uses execvp/argv semantics without shell interpolation. scout beam enforces both endpoints' configured read roots, blocks sensitive and symlinked paths, and caps each transfer at 64 MiB.

scout exec and scout emit accept only these 18 typed commands (ALLOWED_READ_COMMANDS in src/synapse/command_policy.rs):

cat, head, tail, grep, rg, ls, tree, wc, uniq, diff, stat, file, du, df, pwd, hostname, uptime, whoami

git is deliberately excluded, as are shells, interpreters, network clients, and mutating tools (EXEC_DENYLIST). There is no find or sort in the allowlist — use the dedicated scout find action for filesystem search. Per-host custom commands may be enabled via execAllowlist, but receive a zero-argument policy until a typed argument policy is registered.

Distribution Contract

The source of truth for release identity is the version shared by Cargo.toml, .release-please-manifest.json, packages/synapse-rmcp/package.json, release artifacts, and server.json.

Distribution/version invariants:

• The npm package downloads the matching GitHub Release binary.
• The installed binary remains synapse.
• server.json must point at ghcr.io/dinglebear-ai/synapse:<version>.
• Plugin manifests stay versionless where marketplaces derive identity from git state.
• Generated docs and schemas must come from source-controlled generation inputs; curated README/docs should point at source-of-truth files for details.

Verification

just validate-plugin          # plugin manifests, MCP config, monitors, skills
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check

Deployment

For a persistent mounted HTTP server:

SYNAPSE_MCP_HOST=0.0.0.0 \
SYNAPSE_MCP_PORT=40080 \
SYNAPSE_MCP_TOKEN=change-me \
synapse serve

Use bearer or OAuth before exposing the endpoint beyond loopback. Production Docker/Compose notes live in docs/DEPLOYMENT.md and docs/DOCKER.md when present; local operator usage can stay on stdio.

Troubleshooting

• 401 or 403 from /mcp: check bearer/OAuth settings and gateway headers.
• no hosts appear: check SYNAPSE_HOSTS_CONFIG, SYNAPSE_CONFIG_FILE, and ~/.ssh/config.
• destructive actions are refused: confirm the host target and confirmation policy.
• SSH errors: verify OpenSSH known_hosts, mux/socket availability, and host reachability outside Synapse first.

Tools and Actions

flux — Docker infrastructure management