Enables AI clients to manage Docker infrastructure, SSH hosts, ZFS, and file operations through specialized flux and scout tools.
Also known as dinglebear-ai/synapse, synapse, @dinglebear/synapse
- Stars
- 2
- Tools
- 47
- Downloads, 30 days
- 415
- Latest version
- 1.0.0
- Last commit
- Nov 2, 2026
- License
- AGPL-3.0
What is Synapse MCP?
Synapse enables AI clients to manage Docker infrastructure, SSH hosts, ZFS, and file operations through specialized flux and scout tools. It exposes 47 tools, such as flux, scout, info.
Summary generated from the project's README
About Synapse MCP server
Managing Docker infrastructure and remote host inspection from an AI client is what Synapse RMCP enables. This Rust-based server provides a bridge for agents to interact with Docker daemons, Compose projects, ZFS pools, and local or SSH-connected filesystems. It is designed for developers and operators who need to automate infrastructure workflows through specialized tools.
The server operates via two primary MCP tools: flux, which handles Docker and Compose operations, and scout, which manages host inspection, log retrieval, and file transfers. Users can connect using stdio for local development or via streamable HTTP for remote access. When using HTTP, authentication is handled through bearer tokens or Google OAuth.
Security is a core focus, with the server implementing read and write scopes to separate inspection from mutation. Destructive actions require explicit confirmation, and file transfers are bounded by size limits and path restrictions. The system relies on existing SSH trust and local configurations rather than requiring users to pass secrets directly as tool arguments.
What you can do with it
- 1Perform safe file operationsThe server allows for reading files and transferring data within strict security boundaries and size limits.
Written from the project's README. Every use case is checked against a quote from it.
How to install Synapse MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Synapse MCP in Claude Code
$ claude mcp add synapse -- npx -y @dinglebear/synapseInstall Synapse MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@dinglebear/synapse"
]
}
}
}Install Synapse MCP in VS Code
.vscode/mcp.json
{
"servers": {
"synapse": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dinglebear/synapse"
]
}
}
}Install Synapse MCP in VS Code CLI
$ code --add-mcp '{"name":"synapse","type":"stdio","command":"npx","args":["-y","@dinglebear/synapse"]}'Install Synapse MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@dinglebear/synapse"
]
}
}
}Install Synapse MCP in Codex
$ codex mcp add synapse -- npx -y @dinglebear/synapseInstall Synapse MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.synapse] command = "npx" args = ["-y", "@dinglebear/synapse"]
Install Synapse MCP in Gemini CLI
$ gemini mcp add -s user synapse npx -- -y @dinglebear/synapseInstall Synapse MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@dinglebear/synapse"
]
}
}
}Synapse MCP tools 47
Detected from the READMEfluxscoutinfoimagesnetworksvolumespullbuildrmiprunelistinspect
| flux | — | |
| scout | — | |
| info | — | |
| images | — | |
| networks | — | |
| volumes | — | |
| pull | — | |
| build | — | |
| rmi | — | |
| prune | — | |
| list | — | |
| inspect | — |
Show all 47 toolsShow fewer tools
logsstatstopsearchstartstoprestartpauseresumerecreateexecstatusuptimeresourcesservicesnetworkmountsportsdoctordownrefreshhelpnodespeekfinddeltaemitbeampoolsdatasetssnapshotssyslogjournaldmesgauth
| logs | — | |
| stats | — | |
| top | — | |
| search | — | |
| start | — | |
| stop | — | |
| restart | — | |
| pause | — | |
| resume | — | |
| recreate | — | |
| exec | — | |
| status | — | |
| uptime | — | |
| resources | — | |
| services | — | |
| network | — | |
| mounts | — | |
| ports | — | |
| doctor | — | |
| down | — | |
| refresh | — | |
| help | — | |
| nodes | — | |
| peek | — | |
| find | — | |
| delta | — | |
| emit | — | |
| beam | — | |
| pools | — | |
| datasets | — | |
| snapshots | — | |
| syslog | — | |
| journal | — | |
| dmesg | — | |
| auth | — |
Configuration
RUST_LOGTracing filter for Synapse logs.
SYNAPSE_CONFIG_FILEPath to a host configuration file.
SYNAPSE_HOMEOptional Synapse appdata directory.
SYNAPSE_HOSTS_CONFIGInline host topology as a JSON array.
SYNAPSE_MCP_AUTH_MODESYNAPSE_MCP_HOSTSYNAPSE_MCP_PORTSYNAPSE_MCP_TOKENSYNAPSE_RMCP_RELEASE_BASE_URLOptional release download base URL override.
SYNAPSE_RMCP_REPOOptional GitHub owner/repo override for release asset downloads.
SYNAPSE_RMCP_VERSIONOptional GitHub release tag override for the downloaded Synapse binary.
| Name | Description | |
|---|---|---|
| RUST_LOG | Tracing filter for Synapse logs. | |
| SYNAPSE_CONFIG_FILE | Path to a host configuration file. | |
| SYNAPSE_HOME | Optional Synapse appdata directory. | |
| SYNAPSE_HOSTS_CONFIG | Inline host topology as a JSON array. | |
| SYNAPSE_MCP_AUTH_MODE | — | |
| SYNAPSE_MCP_HOST | — | |
| SYNAPSE_MCP_PORT | — | |
| SYNAPSE_MCP_TOKEN | — | |
| SYNAPSE_RMCP_RELEASE_BASE_URL | Optional release download base URL override. | |
| SYNAPSE_RMCP_REPO | Optional GitHub owner/repo override for release asset downloads. | |
| SYNAPSE_RMCP_VERSION | Optional GitHub release tag override for the downloaded Synapse binary. |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubsynapse-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:
fluxmanages Docker infrastructure, containers, Compose projects, and host inspection.scouthandles 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
| 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:
{"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.jsonmust point atghcr.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
401or403from/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
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 host, container_id |
stop |
synapse:write |
Stop a running container (destructive); requires host, container_id |
restart |
synapse:write |
Restart a container; requires host, container_id |
pause |
synapse:write |
Pause a running container; requires host, container_id |
resume |
synapse:write |
Resume a paused container; requires host, container_id |
pull |
synapse:write |
Pull latest image for a container; requires host, container_id |
recreate |
synapse:write |
Recreate container with image pull (destructive); requires host, container_id; optional pull (default true) |
exec |
synapse:write |
Execute command inside container (destructive, execvp); requires host, 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 |
Bounded root-confined file transfer (destructive); requires source_host, source_path, dest_host, dest_path; both paths must be under configured Scout/Compose roots |
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
synapse 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 tool-specific schema and help resources plus read-scoped synapse://hosts, synapse://compose/projects, synapse://status, and synapse://activity. |
| 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
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 |
Delegate auth/authz to an isolated trusted upstream gateway. |
SYNAPSE_MCP_ALLOW_DESTRUCTIVE |
false |
Skip destructive-operation confirmation prompts (loopback only). |
SYNAPSE_MCP_MAX_CONCURRENCY |
50 |
Maximum simultaneous in-flight operational requests. Excess requests receive HTTP 429 with Retry-After. Set to 0 to disable. Public probes, OAuth discovery, and static assets are exempt from concurrency shedding. |
SYNAPSE_MCP_PUBLIC_URL |
unset | OAuth public URL; HTTPS required except loopback development. |
SYNAPSE_HOSTS_CONFIG |
unset | Inline host topology. Omitted host protocols default to SSH; local execution requires protocol: "local". |
See .env.example for the full list of variables, docs/CONFIG.md for
configuration details, and docs/SECURITY.md for transport, path, transfer,
container, and CI runner trust boundaries.
Run
# 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:
{"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
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/synapse → service → JSON
Development
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.mdfor full tool contractsdocs/CONFIG.mdfor environment and authdocs/QUICKSTART.mdfor local smoke testsplugins/synapse/skills/synapse/SKILL.mdfor agent usage guidancetests/parity.rsfor 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.mdfor the curated action contract reference.docs/MCP_SCHEMA.mdfor MCP schema shape and drift expectations.docs/CONFIG.mdfor environment and auth policy.docs/QUICKSTART.mdfor local smoke tests.docs/PLUGINS.mdandplugins/synapse/skills/synapse/SKILL.mdfor agent and marketplace usage.docs/generated/openapi.jsonfor generated OpenAPI output.src/flux_service/,src/scout_service/, andsrc/mcp/for runtime source of truth.
Related Servers
runifi- UniFi controller REST API bridge.rtailscale- Tailscale API bridge for devices, users, and tailnet operations.unraid/runraid- Unraid GraphQL bridge for NAS and server management.rapprise- Apprise notification fan-out bridge for many delivery backends.rgotify- Gotify push notification bridge for sends, messages, apps, and clients.rarcane- Arcane Docker management bridge for containers and related resources.yarr- Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.rytdl- Media download and metadata workflow server.cortex- Syslog and homelab log aggregation MCP server.axon- RAG, crawl, scrape, extract, and semantic search project.labby- 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.
Synapse MCP questions
How do I add Synapse MCP to Claude Code?
Run claude mcp add synapse -- npx -y @dinglebear/synapse in your terminal. Add --scope user to make it available in every project.
How do I add Synapse MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Synapse MCP provide?
It exposes 47 tools, including flux, scout, info, images, networks.
What tools does Synapse expose to MCP clients?
It exposes two primary tools: 'flux' for Docker and Compose infrastructure management, and 'scout' for host inspection, file operations, and log retrieval.
How can I install Synapse for immediate use?
You can use the npm launcher to access the MCP or CLI without a manual installation by running 'npx -y @dinglebear/synapse mcp'.
Does Synapse allow arbitrary shell access?
No, it is not intended for arbitrary shell access. It uses an allowlist of 18 specific commands for execution to maintain safety.
What authentication methods are supported for the HTTP interface?
The mounted HTTP interface supports both bearer token and Google OAuth authentication modes.