Synapse RMCP

Official

by jmagar · Rust

Rust MCP and CLI server for Docker, host inspection, SSH, logs, ZFS, and safe file operations.

Topics

automationclaude-codeclicodexdockerdocker-composefile-operationsgeminihomelabhost-inspectionlogsmcpmcp-servermodel-context-protocolrmcprustsshzfs

README.md21 KBView on GitHub

synapse-rmcp

Rust MCP and CLI server for local Synapse workflows — a full-parity port of synapse-mcp implemented in Rust 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.

Naming
Capabilities And Boundaries
Install
Quickstart
Client Configuration
Runtime Surfaces
MCP Tool Reference
CLI Reference
Configuration
Authentication
Safety And Trust Model
Architecture
Distribution Contract
Development
Verification
Deployment
Troubleshooting
Documentation
Related Servers
License

Naming

The repository is synapse-rmcp, the Rust crate is synapse2, the MCP server identity is synapse2, 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, 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:

bash

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

For a permanent command:

bash

npm i -g synapse-rmcp
synapse --version

From source:

bash

cargo build --release

Quickstart

The first-screen 30-second path is:

bash

npx -y synapse-rmcp mcp

Then configure an MCP client with stdio:

json

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

Start with a read-only call:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scout",
    "arguments": {
      "action": "nodes"
    }
  }
}

Client Configuration

stdio is preferred for local MCP clients:

json

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

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

json

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

Runtime Surfaces

Surface	Status	Purpose
MCP	Required	Agent-facing `flux` and `scout` tools
CLI	Required	Scriptable parity surface for operators
REST	Compatibility	Thin local action endpoint for 14 of 59 actions
Web	Present	Lightweight static admin shell

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:

json

{"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:

bash

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:

bash

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. SSH host trust is delegated to OpenSSH known-hosts behavior, and command execution uses execvp/argv semantics without shell interpolation.

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/jmagar/synapse2:<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

bash

python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check

Deployment

For a persistent mounted HTTP server:

bash

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.

npm / npx

Run the stdio MCP server or CLI without a manual binary install:

bash

npx -y synapse-rmcp --help

MCP clients can use the same launcher:

json

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

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

Across the rmcp family, naming follows repo=<service>-rmcp, npm=<service>-rmcp, and CLI=r<service>. Synapse is the exception: the npm package is synapse-rmcp, but the installed CLI and binary alias remain synapse.

Surfaces

Surface	Status	Purpose
MCP	Required	Agent-facing `flux` and `scout` tools
CLI	Required	Scriptable parity surface
REST	Present	Thin local action endpoint
Web	Present	Lightweight static admin shell

Tools and Actions

`flux` — Docker infrastructure management

`flux docker` — Docker daemon operations (9 actions)

Subaction	Scope	Description
`info`	`synapse:read`	Docker daemon information
`df`	`synapse:read`	Docker disk usage
`images`	`synapse:read`	List Docker images; `dangling_only` to filter untagged
`networks`	`synapse:read`	List Docker networks
`volumes`	`synapse:read`	List Docker volumes
`pull`	`synapse:write`	Pull a Docker image; requires `host`, `image`
`build`	`synapse:write`	Build a Docker image; requires `host`, `context`, `tag`; optional `dockerfile`, `no_cache`
`rmi`	`synapse:write`	Remove a Docker image; requires `host`, `image`, `force=true`
`prune`	`synapse:write`	Remove unused resources; requires `host`, `prune_target`, `force=true`

`flux container` — Container lifecycle + inspection (14 actions)

Subaction	Scope	Description
`list`	`synapse:read`	List containers; optional `state`, `name_filter`, `image_filter`, `label_filter`
`inspect`	`synapse:read`	Detailed container info; requires `container_id`; optional `summary`
`logs`	`synapse:read`	Container logs; requires `container_id`; optional `lines`, `since`, `until`, `grep`, `stream`
`stats`	`synapse:read`	Resource usage stats; optional `container_id`
`top`	`synapse:read`	Show running processes; requires `container_id`
`search`	`synapse:read`	Full-text search by name/image/labels; requires `query`
`start`	`synapse:write`	Start a stopped container; requires `container_id`
`stop`	`synapse:write`	Stop a running container (destructive); requires `container_id`
`restart`	`synapse:write`	Restart a container; requires `container_id`
`pause`	`synapse:write`	Pause a running container; requires `container_id`
`resume`	`synapse:write`	Resume a paused container; requires `container_id`
`pull`	`synapse:write`	Pull latest image for a container; requires `container_id`
`recreate`	`synapse:write`	Recreate container with image pull (destructive); requires `container_id`; optional `pull` (default true)
`exec`	`synapse:write`	Execute command inside container (destructive, execvp); requires `container_id`, `command` array

`flux host` — Host inspection (9 actions)

Subaction	Scope	Description
`status`	`synapse:read`	Check Docker connectivity on a host
`info`	`synapse:read`	OS, kernel, architecture
`uptime`	`synapse:read`	System uptime
`resources`	`synapse:read`	CPU, memory, disk usage
`services`	`synapse:read`	Systemd service status; requires `host`; optional `state`, `service`
`network`	`synapse:read`	Network interfaces
`mounts`	`synapse:read`	Mounted filesystems; requires `host`
`ports`	`synapse:read`	Port mappings; requires `host`; optional `protocol`, `limit`, `offset`
`doctor`	`synapse:read`	Diagnostic checks; requires `host`; optional `checks` (comma-separated)

`flux compose` — Docker Compose project management (10 actions)

Subaction	Scope	Description
`list`	`synapse:read`	List all Docker Compose projects; requires `host`
`status`	`synapse:read`	Get project service status; requires `host`, `project`; optional `service`
`up`	`synapse:write`	Start a compose project; requires `host`, `project`
`down`	`synapse:write`	Stop a compose project (destructive); requires `host`, `project`; optional `remove_volumes`, `force`
`restart`	`synapse:write`	Restart a compose project (destructive); requires `host`, `project`
`recreate`	`synapse:write`	Recreate compose containers (destructive); requires `host`, `project`
`logs`	`synapse:read`	Get project logs; requires `host`, `project`; optional `service`, `lines`, `since`
`build`	`synapse:write`	Build compose project images; requires `host`, `project`; optional `service`
`pull`	`synapse:write`	Pull compose project images; requires `host`, `project`; optional `service`
`refresh`	`synapse:read`	Refresh compose project cache; requires `host`

`flux help` — Auto-generated flux docs

Action	Scope	Description
`help`	public	Return flux action reference; optional `topic` (e.g. `"container:list"`), `format` (`markdown`\|`json`)

`scout` — SSH/local host inspection

Scout simple actions (9 actions)

Action	Scope	Description
`nodes`	`synapse:read`	List all configured SSH hosts
`peek`	`synapse:read`	Read a file or directory listing; requires `host`, `path`; optional `tree`, `depth`
`find`	`synapse:read`	Find files by glob; requires `host`, `path`, `pattern`; optional `depth`, `limit`
`ps`	`synapse:read`	List processes; requires `host`; optional `sort` (`cpu`\|`mem`\|`pid`\|`time`), `grep`, `user`, `limit`
`df`	`synapse:read`	Disk usage; requires `host`; optional `path`
`delta`	`synapse:read`	Compare files or content; requires `source_host`, `source_path`; then either `target_host`+`target_path` or `content`
`exec`	`synapse:write`	Execute allowlisted command (destructive, execvp); requires `host`, `command`; optional `path`, `args`, `timeout_secs`
`emit`	`synapse:write`	Multi-host execution (destructive); requires `targets` array, `command`; optional `args`, `timeout_secs`
`beam`	`synapse:write`	File transfer between hosts (destructive); requires `source_host`, `source_path`, `dest_host`, `dest_path`

`scout zfs` — ZFS introspection (3 subactions)

Subaction	Scope	Description
`pools`	`synapse:read`	List ZFS pools; requires `host`; optional `pool` name filter
`datasets`	`synapse:read`	List ZFS datasets; requires `host`; optional `pool`, `dataset_type`, `recursive`
`snapshots`	`synapse:read`	List ZFS snapshots; requires `host`; optional `pool`, `dataset`, `limit`

`scout logs` — Log retrieval (4 subactions)

Subaction	Scope	Description
`syslog`	`synapse:read`	Read `/var/log/syslog` (falls back to `/var/log/messages`); requires `host`; optional `lines`, `grep`
`journal`	`synapse:read`	Read systemd journal; requires `host`; optional `lines`, `unit`, `priority`, `since`, `until`, `grep`
`dmesg`	`synapse:read`	Read kernel ring buffer; requires `host`; optional `lines`, `grep`
`auth`	`synapse:read`	Read `/var/log/auth.log` (falls back to `/var/log/secure`); requires `host`; optional `lines`, `grep`

`scout help` — Auto-generated scout docs

Action	Scope	Description
`help`	public	Return scout action reference; optional `topic` (e.g. `"zfs:pools"`), `format` (`markdown`\|`json`)

Known Parity Gaps

synapse2 achieves action-level parity with synapse-mcp — all 59 production actions from synapse-mcp/docs/INVENTORY.md are implemented. However, the following features from the original TypeScript server are not yet ported:

Not ported

Feature	Description
`claude/channel` notifications	Original forwards Docker events and log tails as `notifications/claude/channel` MCP notifications. No equivalent exists in Rust.
Templated MCP resources	Original exposes `synapse://hosts/{host}`, `synapse://hosts/{host}/stacks`, `synapse://stacks`, `synapse://stacks/{host}/{stack}`, `synapse://stacks/{host}/{stack}/env`, `synapse://containers/{host}`, `synapse://containers/{host}/{id}`. Rust exposes schema resources, `synapse://hosts`, `synapse://compose/projects`, and help resources.
Root SSH login gate	Original gates `sshUser=root` through elicitation unless `SYNAPSE_ALLOW_ROOT_LOGIN=true`. Rust has destructive-operation elicitation but no root-login gate.
TOFU fingerprint store	Original persists fingerprints to `~/.config/synapse/known_hosts.json` and rejects changed fingerprints. Rust uses strict OpenSSH `known_hosts` with wildcard warnings — different operator behavior.
`SYNAPSE_EXCLUDE_HOSTS`	Original env var to exclude hosts from fleet discovery is absent in Rust.
`SYNAPSE_MCP_ALLOW_YOLO`	Original "skip all confirmation gates" mode. Rust has `SYNAPSE_MCP_ALLOW_DESTRUCTIVE` (per-restart override, loopback-only), which is not identical.
`SYNAPSE_DEBUG_ERRORS`	Original opt-in mode that returns full internal error detail. Rust always sanitizes internal tool errors.
`git` in exec allowlist	Original includes `git` in `ALLOWED_READ_COMMANDS` with flag guards. Rust deliberately excludes `git`.

Configuration

bash

SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me

Key environment variables:

Variable	Default	Description
`SYNAPSE_MCP_HOST`	`127.0.0.1`	Bind host for HTTP transport.
`SYNAPSE_MCP_PORT`	`40080`	Bind port for HTTP transport.
`SYNAPSE_MCP_TOKEN`	unset	Static bearer token for auth.
`SYNAPSE_MCP_NO_AUTH`	`false`	Disable auth for loopback development only.
`SYNAPSE_NOAUTH`	`false`	Trusted-gateway no-auth mode for non-loopback deployments.
`SYNAPSE_MCP_ALLOW_DESTRUCTIVE`	`false`	Skip destructive-operation confirmation prompts (loopback only).
`SYNAPSE_MCP_MAX_CONCURRENCY`	`50`	Maximum simultaneous in-flight requests on `/mcp` and `/v1/synapse2`. Excess requests are queued, not rejected. Set to `0` to disable. `/health` and `/status` are exempt.

See .env.example for the full list of variables and docs/CONFIG.md for auth configuration details.

Run

bash

# Start MCP server (stdio transport)
cargo run -- mcp

# Start HTTP server
cargo run -- serve

# CLI examples
cargo run -- flux docker info
cargo run -- flux container list
cargo run -- flux compose list --host myhost
cargo run -- scout nodes
cargo run -- scout exec --host myhost --command hostname
cargo run -- scout zfs pools --host myhost
cargo run -- scout logs journal --host myhost --unit docker

MCP examples:

json

{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"flux","arguments":{"action":"container","subaction":"list","state":"running"}}
{"name":"flux","arguments":{"action":"compose","subaction":"status","host":"myhost","project":"mystack"}}
{"name":"scout","arguments":{"action":"nodes"}}
{"name":"scout","arguments":{"action":"exec","host":"myhost","command":"hostname"}}
{"name":"scout","arguments":{"action":"zfs","subaction":"pools","host":"myhost"}}
{"name":"scout","arguments":{"action":"logs","subaction":"journal","host":"myhost","unit":"docker"}}

Architecture

text

FluxService   (src/flux_service/)  Docker/container/compose/host ops
ScoutService  (src/scout_service/) SSH/exec/fs/zfs/logs ops
      ↓ via SynapseService facade (src/app.rs)
MCP shims     (src/mcp/tools.rs)  tool args → service → Value
CLI shim      (src/cli.rs)        argv → service → stdout
REST layer    (src/api.rs)        POST /v1/synapse2 → service → JSON

Development

bash

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release

just dev     # serve with no auth (loopback, dev mode)
just test    # cargo test
just lint    # clippy
just fmt     # cargo fmt

Useful docs:

docs/API.md for full tool contracts
docs/CONFIG.md for environment and auth
docs/QUICKSTART.md for local smoke tests
plugins/synapse2/skills/synapse2/SKILL.md for agent usage guidance
tests/parity.rs for automated parity verification against synapse-mcp INVENTORY

Documentation

This README is curated for first-run orientation and high-level action discovery. Source-of-truth docs and code are split as follows:

docs/API.md for the curated action contract reference.
docs/MCP_SCHEMA.md for MCP schema shape and drift expectations.
docs/CONFIG.md for environment and auth policy.
docs/QUICKSTART.md for local smoke tests.
docs/PLUGINS.md and plugins/synapse2/skills/synapse2/SKILL.md for agent and marketplace usage.
docs/generated/openapi.json for generated OpenAPI output.
src/flux_service/, src/scout_service/, and src/mcp/ for runtime source of truth.

unifi-rmcp / rustifi - UniFi controller REST API bridge.
tailscale-rmcp / rustscale - Tailscale API bridge for devices, users, and tailnet operations.
unraid-rmcp / unrust - Unraid GraphQL bridge for NAS and server management.
apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.
gotify-rmcp - Gotify push notification bridge for sends, messages, apps, and clients.
arcane-rmcp - Arcane Docker management bridge for containers and related resources.
yarr-rmcp - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
ytdl-mcp - Media download and metadata workflow server.
cortex - Syslog and homelab log aggregation MCP server.
axon - RAG, crawl, scrape, extract, and semantic search project.
lab - Homelab control plane and Labby gateway project.
lumen - Local semantic code search MCP server.
nugs - Project/package management helper for local agent workflows.
agentcast - Agent transcript and activity publishing project.
soma - RMCP scaffold/runtime template for new provider-backed servers.

License

MIT

Install

Configuration

Environment variables

SYNAPSE_HOME

Optional Synapse appdata directory.

SYNAPSE_HOSTS_CONFIG

Inline host topology as a JSON array.

SYNAPSE_CONFIG_FILE

Path to a host configuration file.

SYNAPSE_RMCP_VERSION

Optional GitHub release tag override for the downloaded Synapse binary.

SYNAPSE_RMCP_REPOdefault jmagar/synapse-rmcp

Optional GitHub owner/repo override for release asset downloads.

SYNAPSE_RMCP_RELEASE_BASE_URL

Optional release download base URL override.

RUST_LOGdefault info,rmcp=warn

Tracing filter for Synapse logs.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "synapse-rmcp": {
      "command": "npx",
      "args": [
        "-y",
        "synapse-rmcp@0.5.4",
        "mcp"
      ],
      "env": {
        "SYNAPSE_HOME": "<YOUR_SYNAPSE_HOME>",
        "SYNAPSE_HOSTS_CONFIG": "<YOUR_SYNAPSE_HOSTS_CONFIG>",
        "SYNAPSE_CONFIG_FILE": "<YOUR_SYNAPSE_CONFIG_FILE>",
        "SYNAPSE_RMCP_VERSION": "<YOUR_SYNAPSE_RMCP_VERSION>",
        "SYNAPSE_RMCP_REPO": "jmagar/synapse-rmcp",
        "SYNAPSE_RMCP_RELEASE_BASE_URL": "<YOUR_SYNAPSE_RMCP_RELEASE_BASE_URL>",
        "RUST_LOG": "info,rmcp=warn"
      }
    }
  }
}

Topics

synapse-rmcp

Contents

Naming

Capabilities And Boundaries

Install

Quickstart

Client Configuration

Runtime Surfaces

MCP Tool Reference

CLI Reference

Authentication

Safety And Trust Model

Distribution Contract

Verification

Deployment

Troubleshooting

npm / npx

Surfaces

Tools and Actions

flux — Docker infrastructure management

flux docker — Docker daemon operations (9 actions)

flux container — Container lifecycle + inspection (14 actions)

flux host — Host inspection (9 actions)

flux compose — Docker Compose project management (10 actions)

flux help — Auto-generated flux docs

scout — SSH/local host inspection

Scout simple actions (9 actions)

scout zfs — ZFS introspection (3 subactions)

scout logs — Log retrieval (4 subactions)

scout help — Auto-generated scout docs

Known Parity Gaps

Not ported

Configuration

Run

Architecture

Development

Documentation

Related Servers

License

Install

Configuration

`flux` — Docker infrastructure management

`flux docker` — Docker daemon operations (9 actions)

`flux container` — Container lifecycle + inspection (14 actions)

`flux host` — Host inspection (9 actions)

`flux compose` — Docker Compose project management (10 actions)

`flux help` — Auto-generated flux docs

`scout` — SSH/local host inspection

`scout zfs` — ZFS introspection (3 subactions)

`scout logs` — Log retrieval (4 subactions)

`scout help` — Auto-generated scout docs