Synapse RMCP

What Synapse RMCP MCP server does

The Synapse RMCP MCP server connects an MCP client with Docker infrastructure, Compose projects, local host resources, and SSH-accessible machines. Its interface is split between two action-dispatched tools:

• flux handles Docker daemon information, container operations, Compose workflows, and related host inspection.
• scout provides node discovery, local or SSH-based inspection, filesystem reads and search, logs, ZFS information, allowlisted command execution, multi-host output, and constrained file transfer.

The same capabilities are available through the synapse command-line binary. REST is provided only as a compatibility endpoint for a subset of actions, while the web surface is a lightweight static administration shell rather than a full dashboard.

How it works

MCP calls select a tool and provide an action, with some operations adding a subaction. For example, Docker information is addressed through flux, while node discovery uses scout. The live MCP schema and Rust action definitions are the authoritative references for the available operations.

The server can run over local stdio, which is the preferred path for local MCP clients, or through streamable HTTP at /mcp. HTTP deployments can use bearer-token or Google OAuth authentication. Credentials, SSH settings, host topology, and command allowlists remain server-side or in the local SSH environment; callers do not pass secrets as action arguments.

scout exec and scout emit do not provide an unrestricted shell. The built-in command policy permits typed read-oriented commands such as cat, grep, ls, stat, df, hostname, and uptime. Shells, interpreters, network clients, mutating commands, git, find, and sort are excluded from the standard allowlist. Filesystem search is exposed through a dedicated action.

Setup and configuration

The Synapse RMCP MCP server can be started through the npm launcher without manually installing a binary:

npx -y @dinglebear/synapse mcp

A permanent installation is available with npm i -g @dinglebear/synapse; source builds use cargo build --release. The npm package downloads the matching Rust binary from GitHub Releases, while the installed executable is named synapse.

For stdio, configure the client to run npx -y synapse-rmcp mcp or the installed synapse mcp command. HTTP clients use the configured /mcp URL and can send a bearer token. Common server settings include SYNAPSE_MCP_HOST, SYNAPSE_MCP_PORT, SYNAPSE_MCP_TOKEN, and SYNAPSE_MCP_AUTH_MODE, although local stdio can run without HTTP authentication.

Limitations and notes

The Synapse RMCP MCP server is intended for controlled host and infrastructure workflows, not arbitrary shell access or unaudited remote mutation. Destructive Docker, Compose, execution, and file-transfer operations require explicit host targets and confirmation policy. Read and write scopes are separated, and destructive prompts can only be bypassed through the documented loopback-safe configuration.

SSH trust follows OpenSSH known-hosts behavior. Local execution requires the explicit built-in local host or a local protocol value; omitting the protocol defaults to SSH. File transfer is confined to configured read roots, rejects sensitive and symlinked paths, and is limited to 64 MiB per transfer. The production container includes Docker CLI and Compose tooling but does not include a Docker daemon; Docker access therefore depends on a mounted socket or an SSH-forwarded remote socket.