Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

docs(mcp): recommend Faro Agent Bridge + faro-cli as primary server access

Juan Denis8180ff44743e
diff --git a/docs/MCP_SERVER_ACCESS.md b/docs/MCP_SERVER_ACCESS.md
index dbec99ea..381bda3f 100644
--- a/docs/MCP_SERVER_ACCESS.md
+++ b/docs/MCP_SERVER_ACCESS.md
@@ -25,139 +25,123 @@ For server access, you'd set up an MCP server that lets Claude:
---
-## Option 1: SSH MCP Server (Recommended)
+## Option 1: Faro + Agent Bridge (Recommended)
-This creates an MCP server on your **local machine** that tunnels commands to your remote server via SSH.
+[Faro](https://github.com/jhd3197/Faro) is our own desktop client for SFTP, FTP, SSH, and S3-compatible storage. Its **Agent Bridge** lends the SSH session you've already authenticated in Faro to Claude Code (or any MCP agent) — no SSH keys handed to the agent, no server-side daemon, no extra MCP packages to install.
-### Step 1: Install the SSH MCP Server
+If you already use Faro to manage your servers, this is a two-minute setup.
-```bash
-# On your Windows machine (where Claude Code runs)
-npm install -g @anthropic/mcp-ssh
-```
+### Step 1: Install Faro
-Or use the community one:
-```bash
-npm install -g @yourdevops/mcp-server-ssh
-```
+Grab the installer for your platform from the [Releases page](https://github.com/jhd3197/Faro/releases) (macOS `.dmg`, Windows `.exe`/`.msi`, Linux `.AppImage`/`.deb`/`.rpm`).
-### Step 2: Configure Claude Code
+### Step 2: Connect to Your Server
-Add to your Claude Code MCP config file:
+Add your server in Faro (New Connection → SFTP/SSH) and connect once, so the session is authenticated. Faro can import existing profiles from `~/.ssh/config`, FileZilla, or PuTTY.
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-**Or for Claude Code CLI:** `~/.claude/settings.json`
+### Step 3: Start the Agent Bridge
-```json
-{
- "mcpServers": {
- "serverkit-server": {
- "command": "npx",
- "args": [
- "-y",
- "@anthropic/mcp-ssh",
- "--host", "your-server-ip-or-hostname",
- "--user", "your-username",
- "--key", "C:\\Users\\Juan\\.ssh\\id_rsa"
- ]
- }
- }
-}
-```
-
-### Step 3: SSH Key Setup (if not done)
+1. Open the **Bridge panel** (status-bar pill) and hit **Start**.
+2. Flip on **Allow agent access** for the session you want to share.
+3. Copy the one-liner the panel generates and run it in your project:
```bash
-# Generate SSH key (if you don't have one)
-ssh-keygen -t ed25519 -C "claude-serverkit"
-
-# Copy to server
-ssh-copy-id user@your-server-ip
-
-# Test connection
-ssh user@your-server-ip "echo 'SSH works!'"
+claude mcp add --transport http faro http://127.0.0.1:<port>/mcp \
+ --header "Authorization: Bearer <token>"
```
----
+That's it — Claude Code auto-discovers the Faro tools (`faro_exec`, `faro_list_sessions`, file read/write, sync, diff, search, log tailing, and more).
+### Why this is the recommended path
-## Option 2: Run MCP Server Directly on Your Server
+| Guardrail | What it means |
+|-----------|---------------|
+| 🔒 Localhost only | The bridge binds to `127.0.0.1` on a random port — never exposed to the network |
+| 🔑 Bearer token | Per-launch token required on every request |
+| ☑️ Per-session opt-in | No connection is reachable until you explicitly allow it |
+| 🙋 Per-command approval | Each command pops a prompt in Faro and blocks until you click Approve (configurable) |
+| 📋 Live audit log | Every command, approval, and denial is logged in the panel |
+| 🔐 Zero credential sharing | The agent borrows your authenticated session — it never sees your keys or passwords |
+
+---
-This runs an MCP server **on your Linux server** that Claude connects to.
+## Option 2: faro-cli (Scripting & Terminal Use)
-### Step 1: Install on Server
+`faro-cli` is the standalone CLI that ships with every Faro release (or build it with `cargo build -p faro-cli --release`). It reuses your saved Faro GUI profiles, so there's nothing to reconfigure — useful when you want server access from scripts or a plain terminal rather than through MCP:
```bash
-# SSH into your server
-ssh user@your-server
+# File ops — any backend, using your saved profiles
+faro-cli profiles list
+faro-cli ls prod:/var/log
+faro-cli cp ./report.pdf prod:/var/www/uploads
+faro-cli sync ./site prod:/var/www/site --mirror --dry-run
-# Install Node.js if needed
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-sudo apt-get install -y nodejs
+# Compare and search — remote↔remote works too
+faro-cli diff prod:/etc staging:/etc --hash
+faro-cli search prod:/var/log "OutOfMemory" --content --regex
-# Install MCP bash server
-npm install -g @anthropic/mcp-server-bash
+# Run commands over a saved SSH profile
+faro-cli exec prod 'systemctl status api'
+
+# Drive the running Agent Bridge (goes through Faro's approval + console)
+faro-cli agent exec prod 'journalctl -u api -n 100'
+faro-cli agent exec prod --detach 'apt-get -y upgrade' # background job
```
-### Step 2: Create a Systemd Service
+Path syntax: bare paths are local, `name:/path` references a saved profile.
+
+### Bonus: machines without SSH — Faro Agent
+
+For a box with no SSH server at all (a Windows PC, a Mac, a locked-down LXC), install Faro's own agent and pair it with a 6-digit code over an encrypted, key-pinned link:
```bash
-sudo nano /etc/systemd/system/mcp-serverkit.service
+curl -fsSL https://github.com/jhd3197/Faro/releases/latest/download/install-agentd.sh | sh
```
-```ini
-[Unit]
-Description=MCP Server for ServerKit
-After=network.target
+The paired machine shows up in Faro like any other connection — browsable, and reachable by the Agent Bridge and `faro-cli` just like an SSH server.
-[Service]
-Type=simple
-User=your-username
-WorkingDirectory=/var/serverkit
-ExecStart=/usr/bin/npx @anthropic/mcp-server-bash
-Restart=on-failure
-Environment=MCP_PORT=3100
+---
-[Install]
-WantedBy=multi-user.target
-```
+## Option 3: ServerKit "Open in Faro" Extension
-```bash
-sudo systemctl enable mcp-serverkit
-sudo systemctl start mcp-serverkit
-```
+The [serverkit-faro](https://github.com/jhd3197/serverkit-faro) extension adds an **"Open in Faro"** button to your ServerKit panel's Services, Domains, and WordPress pages. Clicking it opens Faro with the connection editor prefilled for that site (a `faro://connect?...` deep link — it never connects on its own and never carries credentials).
-### Step 3: Expose via SSH Tunnel (Secure)
+Workflow: ServerKit panel → click "Open in Faro" → connect → start the Agent Bridge → Claude Code has access. No manual host/path copying.
+
+---
-Don't expose MCP directly to the internet. Use an SSH tunnel:
+## Alternative: Generic SSH MCP Servers
+
+If you don't want to use Faro, you can wire Claude Code to your server over plain SSH instead. These work, but they mean managing SSH keys and MCP packages yourself, and they lack Faro's approval prompts and audit log.
+
+### A. SSH MCP server package
```bash
-# On your Windows machine, create persistent tunnel
-ssh -L 3100:localhost:3100 user@your-server -N
+npm install -g @anthropic/mcp-ssh
```
-### Step 4: Configure Claude Code
+Add to your Claude Code MCP config (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"serverkit-server": {
"command": "npx",
- "args": ["-y", "@anthropic/mcp-client-proxy", "--port", "3100"]
+ "args": [
+ "-y",
+ "@anthropic/mcp-ssh",
+ "--host", "your-server-ip-or-hostname",
+ "--user", "your-username",
+ "--key", "C:\\Users\\Juan\\.ssh\\id_rsa"
+ ]
}
}
}
```
----
-
-## Option 3: Simple Bash MCP (Easiest)
-
-Use the built-in bash MCP with SSH as the shell:
+### B. Plain SSH as the MCP command
-### Claude Code Settings
-
-Add to `~/.claude/settings.json` or your project's `.claude/settings.json`:
+The simplest variant — just open an SSH session as an MCP tool:
```json
{
@@ -175,7 +159,22 @@ Add to `~/.claude/settings.json` or your project's `.claude/settings.json`:
}
```
-This is the simplest - it just opens an SSH session as an MCP tool.
+### C. MCP server running on the server itself
+
+Run an MCP server on the Linux box as a systemd service and reach it through an SSH tunnel (`ssh -L 3100:localhost:3100 user@your-server -N`). Never expose an MCP port directly to the internet.
+
+### SSH key setup (required for all of the above)
+
+```bash
+# Generate SSH key (if you don't have one)
+ssh-keygen -t ed25519 -C "claude-serverkit"
+
+# Copy to server
+ssh-copy-id user@your-server-ip
+
+# Test connection
+ssh user@your-server-ip "echo 'SSH works!'"
+```
---
@@ -184,9 +183,9 @@ This is the simplest - it just opens an SSH session as an MCP tool.
| Risk | Mitigation |
|------|------------|
| Full server access | Create a dedicated user with limited sudo rights |
-| SSH key exposure | Use a dedicated key, not your main one |
-| Accidental destructive commands | Claude will ask before running dangerous commands |
-| Network exposure | Always use SSH tunnels, never expose MCP directly |
+| SSH key exposure | With Faro the agent never sees your keys; otherwise use a dedicated key, not your main one |
+| Accidental destructive commands | Faro asks for approval before each command runs |
+| Network exposure | Faro's bridge is localhost-only; for generic MCP always use SSH tunnels, never expose MCP directly |
### Create a Limited User (Recommended)
@@ -224,30 +223,18 @@ Once configured, you can say things like:
After setup, restart Claude Code and try:
```
-"Use the serverkit-server to run: docker ps"
+"Use Faro to run 'docker ps' on my server"
```
-If configured correctly, I'll be able to run that command on your server and show you the output.
-
----
-
-## Recommended MCP Packages
-
-| Package | Purpose |
-|---------|---------|
-| `@anthropic/mcp-server-bash` | Run bash commands |
-| `@anthropic/mcp-server-filesystem` | Read/write files |
-| `@anthropic/mcp-server-docker` | Docker-specific operations |
-| `@modelcontextprotocol/server-everything` | All-in-one server |
+If configured correctly, Claude will run that command on your server (through Faro's approval prompt) and show you the output.
---
## Next Steps
-1. Decide which option works best for you
-2. Set up SSH key access to your server
-3. Configure the MCP server
-4. Restart Claude Code
-5. Test with a simple command
+1. Install [Faro](https://github.com/jhd3197/Faro/releases) and connect to your server
+2. Start the Agent Bridge and paste the generated `claude mcp add` one-liner
+3. Restart Claude Code
+4. Test with a simple command
Let me know which option you want to try and I can help you set it up step by step!