# Synapse MCP server

> Enables AI clients to manage Docker infrastructure, SSH hosts, ZFS, and file operations through specialized flux and scout tools.

- Repository: https://github.com/dinglebear-ai/synapse
- Page: https://hostedmcp.org/servers/dinglebear-ai/synapse
- Official: yes
- Transport: stdio
- Stars: 2
- License: AGPL-3.0
- Latest version: 1.0.0

## Install

### Claude Code

```sh
claude mcp add synapse -- npx -y @dinglebear/synapse
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": [
        "-y",
        "@dinglebear/synapse"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "synapse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dinglebear/synapse"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"synapse","type":"stdio","command":"npx","args":["-y","@dinglebear/synapse"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": [
        "-y",
        "@dinglebear/synapse"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add synapse -- npx -y @dinglebear/synapse
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.synapse]
command = "npx"
args = ["-y", "@dinglebear/synapse"]
```

### Gemini CLI

```sh
gemini mcp add -s user synapse npx -- -y @dinglebear/synapse
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": [
        "-y",
        "@dinglebear/synapse"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `RUST_LOG` | no | no | Tracing filter for Synapse logs. |
| `SYNAPSE_CONFIG_FILE` | no | no | Path to a host configuration file. |
| `SYNAPSE_HOME` | no | no | Optional Synapse appdata directory. |
| `SYNAPSE_HOSTS_CONFIG` | no | no | Inline host topology as a JSON array. |
| `SYNAPSE_MCP_AUTH_MODE` | no | no |  |
| `SYNAPSE_MCP_HOST` | no | no |  |
| `SYNAPSE_MCP_PORT` | no | no |  |
| `SYNAPSE_MCP_TOKEN` | no | no |  |
| `SYNAPSE_RMCP_RELEASE_BASE_URL` | no | no | Optional release download base URL override. |
| `SYNAPSE_RMCP_REPO` | no | no | Optional GitHub owner/repo override for release asset downloads. |
| `SYNAPSE_RMCP_VERSION` | no | no | Optional GitHub release tag override for the downloaded Synapse binary. |

## Tools (47)

- `flux`
- `scout`
- `info`
- `images`
- `networks`
- `volumes`
- `pull`
- `build`
- `rmi`
- `prune`
- `list`
- `inspect`
- `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`

## FAQ

### 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.
