Synapse MCP

MCP (Model Context Protocol) server providing Flux (Docker management) and Scout (SSH operations) tools for homelab infrastructure. The neural connection point for your distributed systems.

Designed for use with Claude Code and other MCP-compatible clients.

Features

Flux Tool (Docker Infrastructure Management)

• Container lifecycle: Start, stop, restart, pause/resume, pull, recreate, exec

• Docker Compose: Full project management (up, down, restart, logs, build, pull, recreate)

• Image operations: List, pull, build, remove Docker images

• Host operations: Status checks, resource monitoring, systemd services, network info

• Log retrieval: Advanced filtering with time ranges, grep (safe patterns only), stream selection

• Resource monitoring: Real-time CPU, memory, network, I/O statistics

• Smart search: Find containers by name, image, or labels across all hosts

• Pagination & filtering: All list operations support limits, offsets, and filtering

Scout Tool (SSH Remote Operations)

• File operations: Read files, directory trees, file transfer (beam), diff comparison

• Remote execution: Execute commands with allowlist security

• Process monitoring: List and filter processes by user, CPU, memory

• ZFS management: Pools, datasets, snapshots with health monitoring

• System logs: Access syslog, journald, dmesg, auth logs with filtering (safe grep patterns only)

• Disk monitoring: Filesystem usage across all mounts

• Multi-host operations: Execute commands or read files across multiple hosts (emit)

Infrastructure

• Multi-host support: Manage Docker and SSH across Unraid, Proxmox, bare metal

• Auto-detect local Docker: Automatically adds local Docker socket if available

• Dual transport: stdio for Claude Code, HTTP for remote access

• O(1) validation: Discriminated union pattern for instant schema validation

• SSH connection pooling: 50× faster repeated operations

Tools

The server provides two powerful tools with discriminated union schemas for O(1) validation:

Available Tools

flux

Docker infrastructure management - container, compose, docker, and host operations

scout

SSH remote operations - file, process, and system inspection

Getting Help

Both tools include auto-generated help:

Breaking change from V2: The unified tool has been completely removed and replaced with flux and scout.

Tool 1: flux - Docker Infrastructure Management

4 actions, 40 subactions - State changes, lifecycle control, destructive operations.

Container Operations (action: "container") - 14 subactions

Docker Compose Operations (action: "compose") - 10 subactions

Docker System Operations (action: "docker") - 9 subactions

Host Operations (action: "host") - 7 subactions

Tool 2: scout - SSH Remote Operations

11 actions, 16 operations - Read-mostly remote file and system operations.

Simple Actions (9)

ZFS Operations (action: "zfs") - 3 subactions

Log Operations (action: "logs") - 4 subactions

Compose Auto-Discovery

The MCP server automatically discovers and caches Docker Compose project locations, eliminating the need to specify file paths for every operation.

How It Works

The discovery system uses a multi-layer approach:

1. Cache Check: Looks up project in local cache (.cache/compose-projects/)

2. Docker List: Queries docker compose ls for running projects

3. Filesystem Scan: Scans configured search paths for compose files

4. Error: Returns error if project not found in any layer

Discovery results are cached for 24 hours (configurable via COMPOSE_CACHE_TTL_HOURS environment variable).

Configuration

Add optional composeSearchPaths to your host configuration:

Default search paths: ["/compose", "/mnt/cache/compose", "/mnt/cache/code"] if not specified.

Optional Host Parameter

Most compose operations accept an optional host parameter. When omitted, the system automatically searches all configured hosts in parallel to find the project:

Auto-discovery times out after 30 seconds if the project cannot be found on any host. If a project exists on multiple hosts, you'll receive an error asking you to specify the host parameter explicitly.

Cache Management

• TTL: 24 hours (default, configurable)

• Storage: .cache/compose-projects/ directory (gitignored)

• Invalidation: Automatic when operations fail due to stale paths

• Manual Refresh: Use compose:refresh subaction

Manual Cache Refresh

Force a cache refresh by scanning the filesystem:

Returns a list of discovered projects with their paths and discovery source (docker-ls or filesystem scan).

Architecture

Components:

• HostResolver: Finds which host contains the project (parallel search)

• ComposeDiscovery: Orchestrates cache, docker-ls, and filesystem scanning

• ComposeProjectCache: File-based cache with TTL validation

• ComposeScanner: Filesystem scanning for compose files (respects max depth of 3)

Example Usage

Flux Tool Examples

Scout Tool Examples

Installation

The server will create a .cache/compose-projects/ directory for storing discovered project locations. This directory is automatically gitignored.

Configuration

SSH Config Auto-Loading

Zero configuration required! Synapse-MCP automatically discovers hosts from your ~/.ssh/config file.

All SSH hosts with a HostName directive are automatically available for Docker management via SSH tunneling to the remote Docker socket. Manual configuration is completely optional.

Priority order:

1. Manual config file (highest) - synapse.config.json

2. SYNAPSE_HOSTS_CONFIG environment variable

3. SSH config auto-discovery - ~/.ssh/config

4. Local Docker socket (fallback)

Example SSH config:

Both hosts are immediately available as flux targets with SSH tunneling to /var/run/docker.sock. No additional configuration needed!

Manual override: If you create a synapse.config.json entry with the same name as an SSH host, the manual config completely replaces the SSH config (no merging).

Manual Configuration (Optional)

Create a config file at one of these locations (checked in order):

1. Path in SYNAPSE_CONFIG_FILE env var

2. ./synapse.config.json (current directory)

3. ~/.config/synapse-mcp/config.json

4. ~/.synapse-mcp.json

Example Config

Copy synapse.config.example.json as a starting point:

Note: If /var/run/docker.sock exists and isn't already in your config, it will be automatically added as a host using your machine's hostname. This means the server works out-of-the-box for local Docker without any configuration.

Host Configuration Options

Local vs Remote Execution

The server automatically determines whether to use local execution or SSH based on your host configuration:

Local Execution (No SSH)

Commands run directly on localhost using Node.js for best performance:

Requirements: Host must be localhost/127.x.x.x/::1 AND no sshUser specified.

Benefits:

• ~10x faster than SSH for Compose and host operations

• No SSH key management needed

• Works out of the box

Remote Execution (SSH)

Commands run via SSH on remote hosts or when sshUser is specified:

When SSH is used:

• Host is NOT localhost/127.x.x.x

• sshUser is specified (even for localhost)

• For all Scout operations (file operations always use SSH)

Docker API vs Command Execution

These are independent:

See .docs/local-vs-remote-execution.md for detailed architecture documentation.

Resource Limits & Defaults

Enabling Docker API on Hosts

Unraid

Docker API is typically available at port 2375 by default.

Standard Docker (systemd)

Edit /etc/docker/daemon.json:

Or override the systemd service:

⚠️ Security Note: Exposing Docker API without TLS is insecure. Use on trusted networks only, or set up TLS certificates.

Usage

With Claude Code

Add to ~/.claude/claude_code_config.json:

Or if your config is in one of the default locations, you can skip the env entirely:

Then in Claude Code:

HTTP Mode

For remote access or multi-client scenarios:

Environment variables for HTTP mode:

• PORT: Server port (default: 3000)

• HOST: Bind address (default: 127.0.0.1)

CLI Help

Example Interactions

Flux Tool - Container Management

Flux Tool - Log Analysis

Scout Tool - Remote File Access

Scout Tool - ZFS Health Check

Scout Tool - System Logs

Security

Path Traversal Protection (CWE-22)

The image_build tool implements strict path validation to prevent directory traversal attacks:

• Absolute paths required: All paths (context, dockerfile) must start with /

• Traversal blocked: Paths containing .. or . components are rejected

• Character validation: Only alphanumeric, dots (in filenames), hyphens, underscores, and forward slashes allowed

• Pre-execution validation: Paths validated before SSH commands are executed

Example of rejected paths:

General Security Notes

• Docker API on port 2375 is insecure without TLS

• Always use execFile for shell commands (prevents injection)

• Validate host config fields with regex

• Require force=true for destructive operations

Development

Architecture

Key Architectural Decisions

V3 Schema Refactor - Two Tools Pattern:

• Flux: 4 actions (container, compose, docker, host) with 40 total subactions

• Scout: 11 actions (9 simple + 2 with subactions) for 16 total operations

• Clean separation: Flux = Docker/state changes, Scout = SSH/read operations

• Total: 56 discriminator keys across both tools

Discriminated Union for O(1) Validation:

• Flux: Composite action_subaction discriminator (container:list, compose:up, etc.)

• Scout: Primary action discriminator with nested discriminators for zfs and logs

• Validation latency: <0.005ms average across all operations

• Zero performance degradation regardless of which operation is called

Help System:

• Auto-generated help handlers for both tools

• Introspects Zod schemas using .describe() metadata

• Supports topic-specific help (e.g., flux help container:logs)

• Available in markdown or JSON format

SSH Connection Pooling:

• 50× faster for repeated operations

• Automatic idle timeout and health checks

• Configurable pool size and connection reuse

• Transparent integration (no code changes required)

Test Coverage:

• Unit tests for all services, schemas, and tools

• Integration tests for end-to-end workflows

• Performance benchmarks for schema validation

• TDD approach for all new features

Performance

Schema Validation

Both Flux and Scout tools use Zod discriminated union for O(1) constant-time schema validation:

• Validation latency: <0.005ms average across all 55 operations

• Flux optimization: Composite action_subaction discriminator with preprocessor

• Scout optimization: Primary action discriminator with nested discriminators for zfs/logs

• Consistency: All operations perform identically fast (no worst-case scenarios)

Flux inputs are automatically preprocessed to inject the action_subaction discriminator key.

SSH Connection Pooling

All SSH operations use connection pooling for optimal performance:

• 50× faster for repeated operations

• Connections reused across compose operations

• Automatic idle timeout and health checks

• Configurable via environment variables

See docs/ssh-connection-pooling.md for details.

Key Benefits:

• Eliminate 250ms connection overhead per operation

• Support high-concurrency scenarios (configurable pool size)

• Automatic connection cleanup and health monitoring

• Zero code changes required (transparent integration)

Benchmarks

Run performance benchmarks:

Expected results:

• Worst-case validation: <0.005ms (0.003ms typical)

• Average-case validation: <0.005ms (0.003ms typical)

• Performance variance: <0.001ms (proves O(1) consistency)

License

MIT