rc-mcp

README

rc-mcp

A personal fleet remote-control system built on the Model Context Protocol (MCP). It lets you inspect and control your own Linux desktop machines from any MCP-capable LLM client — Claude Desktop, Claude Code, or any other spec-compliant MCP host.

You are not a multi-tenant service here: one operator, their own machines. There's no user management or RBAC — the security model is about keeping your LLM client from doing anything you didn't approve, not about isolating users from each other.

How it fits together

 MCP client (Claude Desktop, Claude Code, ...)
          │  MCP over Streamable HTTP (bearer token)
          ▼
   rc-mcp-server  ──────────────  admin API + web UI (loopback only)
          │  WebSocket (device token, outbound from the agent)
          ▼
   rc-mcp-agent  (runs on each controlled machine)
          │
          ▼
   shell, filesystem, processes, screenshots, sysinfo, input

• rc-mcp-server is a relay hub. It speaks MCP to LLM clients and a WebSocket wire protocol to agents, and routes tool calls between them. It never executes any tool logic itself.
• rc-mcp-agent runs on each machine you want to control. It dials out to the server (no inbound port needed on the desktop — NAT/firewall friendly) and does the actual work: running commands, reading files, taking screenshots, and so on.
• Every capability an agent exposes is opt-in and configured per-agent, so a laptop you rarely touch can run with just sysinfo, while a workstation can run with everything enabled.

The full protocol and architecture design lives in docs/specs/backend.md; this README is the practical "how do I run this" guide.

What an LLM client can do through it

Capability	Tools
Shell	shell_exec (one-shot), shell_session_start/write/close (interactive PTY sessions)
Filesystem	fs_read, fs_write, fs_list, fs_delete, fs_stat
Processes	process_list, process_info, process_signal
Screenshots	screenshot_capture, screenshot_watch (periodic, streamed) — X11 and Wayland
System info	sysinfo_get
Input injection	input_key, input_mouse_click, input_mouse_move, input_type — off by default, every call requires confirmation with no bypass

Plus MCP resources (clients://list, job://{id}, sysinfo://.../overview, audit://log, shell://sessions), three guided prompts (diagnose_system, safe_cleanup, shell_workflow), and argument completion for device IDs and file paths.

Anything that mutates state (running a command, writing a file, killing a process) requires the client to confirm via MCP elicitation before it's dispatched — the agent never receives a destructive call the operator hasn't explicitly approved in that moment. Every call is recorded in an append-only audit log.

Quick start

You'll need Go 1.25+ and, for the container path, Docker.

1. Run the server

export AUTH_TOKEN=$(openssl rand -hex 64)          # required — the server won't start without it
export RC_AUDIT_LOG_PATH=./rc-mcp-audit.log         # production default (/var/log/rc-mcp/...) needs root
export DEVICE_REGISTRY_PATH=./rc-mcp-devices.json   # production default (/var/lib/rc-mcp/...) needs root
go run ./cmd/server

This serves plain ws:// (no TLS) on 0.0.0.0:8080 — fine for same-host or same-LAN testing, but see Docker Compose below for a real deployment.

Or via Docker Compose, which additionally fronts the server with nginx over TLS (see docker-compose.yml and .env.example for the full settings list):

cp .env.example .env   # fill in AUTH_TOKEN at minimum
# nginx needs a TLS cert; for local dev, a self-signed one is enough
# (see docker/nginx/certs/README.md for the one-liner and the real-CA note)
docker compose up

MCP clients and agents connect through nginx on :443; the admin API stays on 127.0.0.1:9090, loopback only by design (see Security) and never proxied.

2. Pair a machine

On the machine you want to control (use wss://your-server-host/agent/ws instead if you're going through the Docker Compose/nginx TLS path above):

export AGENT_SERVER_URL=ws://127.0.0.1:8080/agent/ws
go run ./cmd/agent

First run has no device token yet, so the agent prints a pairing code (a fresh one each run — don't reuse an old one) and waits:

Pairing code: ABCD-1234
Expires at:   2026-01-01T00:05:00Z
Approve on the server with: curl -X POST http://127.0.0.1:9090/admin/approve -d '{"code":"ABCD-1234"}'

Run that curl command (with your printed code, not the example above) from the server host:

curl -X POST http://127.0.0.1:9090/admin/approve -d '{"code":"ABCD-1234"}'

or open http://127.0.0.1:9090/ in a browser for the same thing with a UI — pending codes, paired devices with revoke, and the audit log. Once approved, the agent saves its device token locally and reconnects on its own from then on, including after the server or machine restarts.

3. Point an MCP client at it

Configure your MCP client (Claude Desktop, Claude Code, etc.) with the server's /mcp endpoint and the AUTH_TOKEN bearer token, e.g. in claude_desktop_config.json or a project's .mcp.json (see docs/examples/mcp-config.json):

{
  "mcpServers": {
    "rc-mcp": {
      "type": "http",
      "url": "https://your-server-host/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

or with the Claude Code CLI:

claude mcp add --transport http rc-mcp https://your-server-host/mcp \
  --header "Authorization: Bearer YOUR_AUTH_TOKEN"

The client will see whichever tools your paired agents have capabilities enabled for.

Configuration

Every setting is an environment variable — see .env.example for the full list with defaults, and docs/specs/backend.md Section 15 for the authoritative descriptions. A few worth knowing up front:

• AGENT_CAPABILITIES (agent side) — comma-separated list of what an agent exposes: shell,screenshot,filesystem,process,sysinfo by default; input is available but never on by default.
• RC_SHELL_SKIP_CONFIRM, RC_FS_SKIP_CONFIRM, RC_PROCESS_SKIP_CONFIRM (server side) — skip the confirmation prompt for that tool group. Input injection has no such flag; it always confirms.
• RC_SHELL_ALLOWLIST / RC_SHELL_DENYLIST — regex patterns (one per line) a shell command must pass before it's ever dispatched.
• RC_GLOBAL_FS_ALLOWED_ROOTS / AGENT_FS_ALLOWED_ROOTS — restrict which absolute paths filesystem tools can touch, enforced server-side and agent-side respectively.
• MCP_SESSION_STORE=redis + REDIS_ADDR — switch from the single-instance in-memory/file-backed defaults to a Redis-backed session store, device registry, and cross-replica dispatch routing, for running more than one server replica. See docs/operations/scaling.md.
• AGENT_AUTO_UPDATE=true — let an agent download, checksum-verify, and install a newer build the server advertises. Off by default. See docs/operations/agent-releases.md.

Security

A few things are load-bearing, not incidental:

• The LLM can never pair, approve, or revoke a device. Pairing approval only exists on the admin API/web UI, which only listens on loopback — there is no code path from the MCP surface to device management.
• Destructive actions require live confirmation via MCP elicitation, shown to the human at the client, not assumed from a prior approval.
• Every tool call is audited, append-only, with the session, target device, tool, and outcome — SHA-256 digested by default, or in full under RC_AUDIT_FULL_ARGS=true for forensic use.
• Agents connect outbound only. No inbound port on the controlled machine, and each connection re-authenticates with a per-device token the server can revoke at any time.

Found a vulnerability? See SECURITY.md for how to report it privately.

Development

go build ./...
go test ./...

This is a plain Go module — no Nx, no JS/TS runtime code. CI runs go build, go vet/golangci-lint, and go test directly. See docs/adr/0001-nx-go-integration.md for the history of why Nx was tried and later dropped.

Docs

• llms.txt — condensed, LLM-oriented index of this repo's docs (see llmstxt.org).
• docs/guides/install-server.md and docs/guides/install-agent.md — install guides beyond this README's quick start: Docker Compose, published images, and systemd services for a from-source install.
• docs/specs/backend.md — the full protocol, wire format, and architecture specification.
• docs/operations/ — running a release pipeline, auto-update, and multi-replica scaling.
• docs/phases/ — how the MVP and post-MVP work was sequenced.
• docs/adr/ — architecture decision records.

License

MIT