Computer Use For All Agents MCP Server

🖥️ Computer use for all agents

A local remote-control system for AI agents: watch your computer's screen live and send mouse/keyboard commands to it. Everything runs on your own machine — no data ever leaves it, no cloud middleman.

---

If You Are an AI Agent

Read AGENT_GUIDE.md first — it is written for you: endpoints, safety gates and working recipes. This README is the human-facing reference.

First ask the server what it is — GET /api/capabilities → platform. Windows: follow the whole guide as written. Linux: check echo $XDG_SESSION_TYPE — X11 is supported (guide → Linux (X11) Usage); Wayland is unsupported: the server refuses to start, HTTP 501 UNSUPPORTED_DISPLAY_SERVER (switch to an X11 session). Full routing lives in AGENT_GUIDE.md → Find Your Environment First.

---

Why Screen Control?

AI agents today can write code and call APIs — but they can't see or touch your desktop. Screen Control gives any agent general-purpose computer use over a clean, safety-gated HTTP/MCP interface:

• Perceive — OCR for text, single frames or a live MJPEG stream for vision-capable models, and a text-only diff endpoint for models that can't consume images at all.
• Act — absolute and relative mouse, Unicode-safe keyboard, window management, background (focus-free) control, virtual desktops.
• Stay safe — token auth, blocked deadly shortcuts, focus guard, a stuck-input watchdog and an emergency failsafe are all enforced server-side, no matter how confused the agent gets.

One process, zero configuration, works with any language that can speak HTTP — or natively through MCP in Claude Desktop, Cursor, VS Code and cloud agents.

Performance Is Agent-Bound

Screen Control is the perception and actuation layer — the eyes and hands. The effective speed and capability of any agent using it are bounded by that agent itself and by the environment it runs in:

• Thinking speed — one action per agent "turn": the perceive → plan → act → verify loop lives in the agent, so model inference latency and reasoning depth directly set the pace. The API itself adds only milliseconds per call.
• Context capacity — screen readings (OCR text, frames, diffs) consume the agent's context window; a larger window means more situational awareness before verification degrades.
• Runtime environment — network latency, MCP/HTTP round-trip overhead, tool-call limits and hosting constraints all stack on top of the loop.

In practice this means: the same repo makes a fast reasoning model fast and capable, and makes a slow model slow — the toolchain is not the bottleneck. Real-time or action-heavy tasks need an agent with fast inference and tight tool-loop latency; slower agents should prefer deliberate, verification-heavy tasks.

---

Table of Contents

• If You Are an AI Agent
• Why Screen Control?
• Features
• Architecture
• Installation
• Linux (X11)
• Quick Start
• API Reference
  • Authentication
  • Screen Capture
  • Mouse Control
  • Keyboard Control
  • OCR (Screen Reading)
  • Vision Access (Image Models)
  • Window Management
  • Focus-Free (Background) Control
  • Virtual Desktops
  • Game Mode
  • Safety Endpoints
• 🤖 For AI Agents
• MCP Support (One-Click Cloud Agents)
• Security Model
• Game Mode Guide
• Vision Access Guide
• Troubleshooting
• Testing
• Contributing
• License

---

Features

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Browser (Web UI)                      │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐ │
│  │  Live     │  │  Control  │  │  Windows / Game Mode   │ │
│  │  View     │  │  Panel    │  │  Panel                 │ │
│  └────┬─────┘  └────┬─────┘  └───────────┬────────────┘ │
│       │              │                     │              │
└───────┼──────────────┼─────────────────────┼──────────────┘
        │              │                     │
        ▼              ▼                     ▼
┌─────────────────────────────────────────────────────────┐
│                  HTTP API (Flask)                        │
│                  127.0.0.1:8745                           │
│                                                         │
│  /api/screenshot    /api/mouse     /api/key              │
│  /api/vision/*      /api/ocr       /api/window           │
│  /api/game          /api/held      /api/release_all      │
│  /api/windows       /api/desktops  /api/desktop          │
│                                                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ Auth Layer  │  │  Watchdog    │  │  OCR Engine  │   │
│  │ (token)     │  │  (30s auto)  │  │  (RapidOCR)  │   │
│  └─────────────┘  └──────────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────┘
        │              │                     │
        ▼              ▼                     ▼
┌─────────────────────────────────────────────────────────┐
│                  control.py (Core)                        │
│                                                         │
│  Screen:  mss (fast capture), PIL (processing)          │
│  Mouse:   pyautogui (absolute), SendInput (relative)    │
│  Keyboard: pyautogui + SendInput+KEYEVENTF_UNICODE      │
│  Windows: Win32 API (EnumWindows, SetForegroundWindow)   │
│  Background: PrintWindow (capture), PostMessage (input)  │
│  Virtual Desktops: pyvda                                 │
│  Game Mode: ClipCursor + MOUSE_MOVE_RELATIVE             │
└─────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│              backends/ (pluggable)           │
│  WindowsBackend  │ LinuxBackend │ MacOSBackend│
│      (full)      │    (X11)     │   (stub)   │
└──────────────────────────────────────────────┘

Coordinates & Concurrency

Per-Monitor DPI awareness. control.py calls SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2) at import time — before the pyautogui import, because pyautogui touches coordinate APIs during import and would otherwise lock the process to the interpreter manifest's default (system-aware). With PMv2 active, every coordinate in the system is a physical pixel end to end: mss capture, OCR bounding boxes, pyautogui/SendInput clicks, ClipCursor. On High-DPI displays (125%/150% scaling) nothing drifts between what OCR reports and where the mouse clicks.

Lock architecture. The server uses two independent locks instead of one global lock:

A slow OCR (3–5 s on a busy screen) no longer freezes concurrent screenshot or vision reads — reads queue behind reads, inputs behind inputs.

Live-Loop Working Principle

This system is designed for a live perceive-act loop, not pre-written command chains:

1. READ — OCR or vision reads the screen before and after every action
2. ONE ACTION — each round sends a single command
3. VERIFY — acceptance is "it appeared on screen", not "I sent it"
4. ADAPT — if verification fails, the next step changes based on what is actually seen

This is enforced by the expect_hwnd guard: typing is refused (409) if the foreground window doesn't match the target.

---

Installation

Pick the version that fits how your agent works:

Skill version

The portable agent skill lives in skills/computer-use/ (SKILL.md plus a full API reference). It teaches any skills-capable agent the perceive-act-verify loop, the safety rules and the endpoint catalogue — the agent then drives a running server.

# Claude Code — user-level (available in every project)
cp -r skills/computer-use ~/.claude/skills/

# Claude Code — this project only
mkdir -p .claude/skills && cp -r skills/computer-use .claude/skills/

For other skill-capable agents, copy the folder into that agent's own skills directory. Either way the server must be running (python server.py) — the skill provides instructions, not a backend.

REST server

cd screen-control
pip install -r requirements.txt

Requirements

Note: The OCR package is large and may take a while to install. If it fails, everything else still works — only the OCR feature is unavailable.

System Requirements

• OS: Windows 10/11 (x64), or Linux (Ubuntu/Mint family, X11 session — see Linux (X11))
• Python: 3.10+
• Display: Any resolution; the system adapts automatically

---

Linux (X11)

Linux is supported with limits (ROADMAP Phase 5) — tested on Linux Mint with Cinnamon in an X11 session; other X11 desktop environments are expected to work. Windows remains the reference backend.

Requirements

• OS: Ubuntu / Linux Mint family (apt-based)
• Session: X11 — check this first:

echo $XDG_SESSION_TYPE    # must print: x11

• Wayland? Not supported — the server fails fast instead of half-working (see Known limitations).
• System packages (installed by the setup script below):

sudo apt install -y xdotool wmctrl imagemagick python3-venv python3-tk python3-dev

xdotool drives input/focus, wmctrl window management, ImageMagick's import captures window pixels (optional — an mss region fallback exists), python3-venv creates the virtualenv and python3-dev lets evdev (game mode) compile from source.

One-command setup

cd screen-control
./install-linux.sh

The script is idempotent and checks, in order: Wayland (exits with a clear message), DISPLAY, the apt packages, the .venv virtualenv, pip install -r requirements.txt, and finally reports whether game mode can work.

uinput permissions (game mode)

Game mode writes to /dev/uinput. Verify access with:

[ -w /dev/uinput ] && echo "game mode: OK" || echo "game mode: unavailable"

If it is unavailable, either remediation works (spec §5.4):

sudo usermod -aG input $USER        # then log out and back in
# — or a udev rule:
echo 'KERNEL=="uinput", MODE="0660", GROUP="input"' | sudo tee /etc/udev/rules.d/99-uinput.rules
sudo udevadm control --reload && sudo udevadm trigger

Everything except game mode works without this access.

Run

./start-server.sh
# → same API as Windows: http://127.0.0.1:8745 (X-Auth-Token from .token)

Known limitations (Linux X11)

Agent note: OCR is the slowest read (≈5–6 s full-screen measured). Prefer /api/vision/frame or /api/stream for repeated reads, use region OCR, and batch reads between actions — see AGENT_GUIDE.md → Linux (X11) Usage.

---

Quick Start

# 1. Start the server
cd screen-control
python server.py

# 2. Open in browser
#    http://127.0.0.1:8745

# 3. Or control via API
TOKEN=$(cat .token)
curl -H "X-Auth-Token: $TOKEN" http://127.0.0.1:8745/api/screenshot -o screen.jpg

---

API Reference

Capabilities

Returns the active backend name and what it can do. Agents should call this first (see ROADMAP.md for the multi-platform plan).

GET /api/capabilities
→ {"ok": true, "backend": "windows",
   "capabilities": {"screen_capture": true, "game_mode": true, ...}}

Feature values: true (supported), false (absent), null (unknown — stub backend), "optional" (depends on an optional dependency).

Platform Support Matrix

Linux X11 is implemented and supported with limits — setup, requirements and the full limitations list are in Linux (X11). Wayland fails fast with UNSUPPORTED_DISPLAY_SERVER (501), and macOS remains a fail-closed stub: every operation returns BACKEND_UNAVAILABLE (501) until ROADMAP Phase 7. Windows is the reference backend.

† Wayland column is hypothetical capability planning only — the server never starts on Wayland (see the note above), so no Wayland cell is currently reachable.

Authentication

Every request must include the X-Auth-Token header. The token is generated on each server start and written to .token.

TOKEN=$(cat .token)

Token bootstrap (for the bundled web UI):

GET /token
→ {"ok": true, "token": "abc123..."}

The /token endpoint answers only loopback callers on a loopback bind: the check uses the accepted socket's peer address (a LAN client cannot spoof it), the Host header guards against DNS rebinding, and the response is never cached. When the server is bound to 0.0.0.0 or is reached from a non-loopback peer, /token returns 403.

---

Screen Capture

GET /api/screenshot

Returns a JPEG screenshot.

curl -H "X-Auth-Token: $TOKEN" -o screen.jpg http://127.0.0.1:8745/api/screenshot
curl -H "X-Auth-Token: $TOKEN" "http://127.0.0.1:8745/api/screenshot?region=0,0,800,600"

GET /api/info

Returns screen dimensions and system state.

{"ok": true, "width": 1920, "height": 1080, "ocr_available": true,
 "failsafe": true, "game_mode": false}

---

Mouse Control

POST /api/mouse

# Click at center of screen
curl -X POST http://127.0.0.1:8745/api/mouse -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"click","x":960,"y":540,"button":"left"}'

# Right-click
curl -X POST http://127.0.0.1:8745/api/mouse -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"click","button":"right","x":960,"y":540}'

# Scroll down
curl -X POST http://127.0.0.1:8745/api/mouse -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"scroll","clicks":-3}'

---

Keyboard Control

POST /api/key

# Press Enter
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"press","key":"enter"}'

# Ctrl+C
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"hotkey","keys":["ctrl","c"]}'

# Type text (Turkish characters supported)
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"type","text":"Merhaba dünya"}'

# Hold W key down (for walking in games)
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"down","key":"w"}'

---

OCR (Screen Reading)

POST /api/ocr

Converts on-screen text to machine-readable format.

{
  "ok": true,
  "text": "Hello World\nFile Edit View",
  "lines": ["Hello World", "File Edit View"],
  "items": [
    {"text": "Hello World", "x": 960, "y": 40},
    {"text": "File Edit View", "x": 100, "y": 15}
  ]
}

# Full screen OCR
curl -X POST http://127.0.0.1:8745/api/ocr -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

# Region-only (faster, ~10x for small regions)
curl -X POST http://127.0.0.1:8745/api/ocr -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"region":[0,0,800,100]}'

---

Vision Access (Image Models)

Three endpoints for models that can consume images:

GET /api/vision/frame

# Half-size greyscale frame as base64 (for text-only models)
curl "http://127.0.0.1:8745/api/vision/frame?scale=0.5&gray=1&format=base64" \
  -H "X-Auth-Token: $TOKEN"

GET /api/stream

MJPEG live stream. Drop into <img src> or consume frame-by-frame.

POST /api/vision/diff

Text-based motion detection — no vision model required.

{
  "ok": true,
  "changed": true,
  "changed_pct": 12.5,
  "bbox": [100, 200, 400, 350],
  "tiles": [
    {"row": 2, "col": 4, "pct": 35.2, "center": [1000, 390]}
  ]
}

---

Window Management

GET /api/windows

List all visible windows.

{
  "ok": true,
  "windows": [
    {
      "hwnd": 123456,
      "title": "My Application",
      "process": "app.exe",
      "pid": 7890,
      "focused": true,
      "rect": [0, 0, 1920, 1080],
      "desktop": 1
    }
  ]
}

POST /api/window

# Focus a window
curl -X POST http://127.0.0.1:8745/api/window -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"hwnd":12345,"action":"focus"}'

# Safe close (with title verification)
curl -X POST http://127.0.0.1:8745/api/window -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"close","hwnd":12345,"expect_title":"Notepad"}'

# Kill process
curl -X POST http://127.0.0.1:8745/api/window -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"kill","hwnd":12345,"pid":7890}'

POST /api/launch

Spawn an application, open a URL, or open a local file. Exactly one of app | url | file. Never runs through a shell: app is a plain command name resolved on PATH ([A-Za-z0-9._+-]+), url/file go through xdg-open.

Launch policy: interpreter and executor names (python*, node, sh/bash/cmd/powershell, env, xargs, sudo, curl, …) are refused with 400 — /api/launch is for GUI applications, not a remote code-execution endpoint.

{"ok": true, "pid": 4321, "window": {"hwnd": ..., "title": "..."}}

With expect_title, window is the match or null (spawn succeeded, no window yet) — the HTTP status stays 200 either way.

curl -X POST http://127.0.0.1:8745/api/launch -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app":"firefox","expect_title":"Mozilla Firefox","timeout":15}'

GET /api/window/wait

Block until a window whose title contains title (case-insensitive substring) appears, then return it. timeout default 10 s, max 30 s; 200 with the window, or 408 OPERATION_TIMEOUT.

curl -H "X-Auth-Token: $TOKEN" \
  "http://127.0.0.1:8745/api/window/wait?title=Notepad&timeout=10"

---

Focus-Free (Background) Control

Read and control windows without stealing focus — the user keeps working on their main desktop.

Linux (X11) note: background control there is focus-first — the target window is focused, then input is sent globally (focus stealing). Only background capture is truly focus-free. See Known limitations.

GET /api/window/capture

Capture a window via PrintWindow (works even on another virtual desktop).

# Capture window as PNG
curl "http://127.0.0.1:8745/api/window/capture?hwnd=12345" \
  -H "X-Auth-Token: $TOKEN" -o window.png

# Capture + OCR in one call
curl "http://127.0.0.1:8745/api/window/capture?hwnd=12345&ocr=1" \
  -H "X-Auth-Token: $TOKEN"

POST /api/window/post

Send input to a window, choosing the delivery path automatically.

Optional mode parameter controls routing:

# Type into a background Notepad
curl -X POST http://127.0.0.1:8745/api/window/post -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hwnd":12345,"action":"type","text":"Hello from background!"}'

Routing rules (mode=auto):

• postmessage — classic Win32 app: background PostMessage, no focus change.
• uia — WinUI/UWP/XAML surface (single DirectX canvas, no Win32 child controls): posted messages are silently swallowed, so the window is focused and the action is replayed through SendInput (client coords converted to screen). This is the documented fallback for modern apps.
• focused — window is already foreground: focused SendInput path.
• invalid — HTTP 409; not a reachable top-level window.

GET /api/window/input-mode

Classify how a window receives input before posting to it. Returns one of focused | postmessage | uia | invalid.

curl "http://127.0.0.1:8745/api/window/input-mode?hwnd=12345" \
  -H "X-Auth-Token: $TOKEN"

WinUI note: New Notepad (and other XAML-hosted apps) has no classic child Edit control to post to — the whole UI is one DirectX surface. input-mode reports uia for these; /api/window/post then automatically uses the focused SendInput path. /api/window/children remains useful for classic apps with real child controls.

GET /api/window/children

List child controls of a window (class name + title + hwnd).

curl "http://127.0.0.1:8745/api/window/children?hwnd=12345" -H "X-Auth-Token: $TOKEN"

---

Virtual Desktops

GET /api/desktops

List all virtual desktops.

POST /api/desktop

curl http://127.0.0.1:8745/api/desktops -H "X-Auth-Token: $TOKEN"

curl -X POST http://127.0.0.1:8745/api/desktop -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"switch","number":2}'

---

Game Mode

# Start game mode
curl -X POST http://127.0.0.1:8745/api/game -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"start","sensitivity":12}'

# Look right
curl -X POST http://127.0.0.1:8745/api/game -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"move","dx":50,"dy":0}'

# Hold W to walk forward
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"down","key":"w"}'

# ... later ...
curl -X POST http://127.0.0.1:8745/api/key -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"up","key":"w"}'

# Stop game mode
curl -X POST http://127.0.0.1:8745/api/game -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{"action":"stop"}'

---

Safety Endpoints

GET /api/held

Returns currently held keys/buttons and watchdog status.

{
  "ok": true,
  "keys": ["w", "shift"],
  "buttons": ["left"],
  "game_mode": true,
  "idle_seconds": 5.2,
  "watchdog_count": 0,
  "last_watchdog": null
}

POST /api/release_all

Emergency: release everything (held keys, mouse buttons, game-mode cursor lock).

curl -X POST http://127.0.0.1:8745/api/release_all -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

---

---

🤖 For AI Agents

A dedicated, comprehensive guide for AI agents (LLMs, vision models, automation frameworks) is available in AGENT_GUIDE.md.

Prefer loading this as a skill instead of browsing docs? Install the Skill version.

It covers:

• Environment routing — find Windows vs Linux (X11/Wayland) first
• Perceive-act loop (read → plan → act → verify)
• Focus guard (expect_hwnd) to prevent wrong-window accidents
• App automation and game control workflows
• Linux (X11) usage: slow-OCR batching, capture semantics, game-mode caveats
• Vision access for image-capable models
• Text-based motion detection
• Bandwidth optimization
• Complete curl examples

---

MCP Support (One-Click Cloud Agents)

Model Context Protocol (MCP) turns this project into a plug-and-play toolbox for any MCP-capable agent: Claude Desktop, Claude Code, Cursor, VS Code Copilot Agent mode, custom cloud agents — no custom glue code, no curl scripts. The agent discovers and calls the tools natively.

How it works

MCP agent (cloud or desktop)
        │  MCP protocol (stdio or streamable-HTTP)
        ▼
  mcp_server.py   ← thin wrapper: tools → HTTP calls, token auto-read
        │  REST + X-Auth-Token (localhost only)
        ▼
  server.py       ← the single source of truth:
                    auth, locks, watchdog, focus guard, all safety rules

mcp_server.py adds no new powers — every safety mechanism (auth token, input/read locks, watchdog, Alt+F4 block, focus guard, failsafe) stays enforced by server.py.

Setup

pip install mcp            # optional dependency (see requirements.txt)
python server.py           # start the REST server first (it writes .token)

The MCP server auto-reads the token from .token (or the SCREEN_CONTROL_TOKEN env var) — zero configuration.

Desktop agents (stdio transport)

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "screen-control": {
      "command": "python",
      "args": ["C:/path/to/screen-control/mcp_server.py"]
    }
  }
}

Claude Code: claude mcp add screen-control -- python C:/path/to/screen-control/mcp_server.py

Cursor / VS Code: add the same entry to their MCP config files.

Remote / cloud agents (streamable-HTTP transport)

python mcp_server.py --http --port 8751
# MCP endpoint: http://127.0.0.1:8751/mcp

The HTTP transport is token-protected: every request must carry the X-Auth-Token header (same token as the REST server). Query-string tokens (?token=...) are rejected by design — URLs leak into proxy/tunnel logs, browser history and shared links, and this token grants full desktop control. Clients that cannot send custom headers should run a local stdio mcp_server.py instead. Only GET /health is open, for liveness probes. DNS-rebinding protection is disabled on this transport deliberately — tunneled requests arrive with a foreign Host header, and the rebinding threat is already covered by the token guard.

For a cloud agent, expose it through a tunnel:

cloudflared tunnel --url http://127.0.0.1:8751
# → prints a https://<random>.trycloudflare.com URL

Then configure the agent's MCP connection with <tunnel-url>/mcp plus the token from .token as a header (X-Auth-Token).

Headerless connectors (scoped keys)

For clients that cannot send custom headers (e.g. web connectors that only take an endpoint URL), create a scoped API key — a persistent, optionally time-limited credential — and embed it in the URL path:

# Create a 24-hour scoped key (requires the server to be running)
curl -X POST http://127.0.0.1:8745/api/keys -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"create","name":"spark","expires_in_hours":24,"scopes":["mcp"]}'

# Connector endpoint becomes:
#   https://<tunnel-url>/mcp/<scoped-key>

Design guarantees (SC-06):

• The master session token is refused in URLs (403) — only scoped keys may travel there
• Keys carry scopes (rest, mcp): a key minted with {"scopes":["mcp"]} cannot call the REST API at all, and any scoped key is refused on admin endpoints (/api/keys, /api/session*) — those accept the master token only
• Scoped keys expire automatically; expired keys authenticate nothing
• Scoped keys are revocable by name at any moment via POST /api/keys ({"action":"revoke","name":"spark"}) — revocation takes effect immediately on every endpoint
• The .apikeys file stores only SHA-256 hashes, never raw keys, and is written with 0600 permissions

⚠️ A tunnel exposes PC control to the internet. Keep the token secret, prefer short-lived tunnels and scoped keys for headerless connectors, and stop the server when not in use.

One-Command Startup (launcher, tunnel opt-in)

start-server.bat automates the whole setup and prints a paste-ready scoped key for your cloud agent:

1. Downloads cloudflared.exe from a pinned release and verifies its SHA-256 against Cloudflare's published checksum (no mutable latest URL, no unverified binary)
2. Stops leftover instances from a previous run
3. Starts the REST server (port 8745) and the MCP HTTP server (port 8751)
4. Waits until both are healthy (/token and /health probes)
5. Starts the quick tunnel only when you opt in with start-server.bat --tunnel, extracts its public URL from tunnel.log, and prints the summary:

 ============================================================
  ALL SYSTEMS RUNNING
 ============================================================
  Local REST API  : http://127.0.0.1:8745
  Local MCP       : http://127.0.0.1:8751/mcp
  Public MCP URL  : https://<random>.trycloudflare.com/mcp

  ------------------------------------------------------------
  PASTE INTO YOUR CLOUD AGENT  (MCP connector settings)
  ------------------------------------------------------------
  Endpoint : https://<random>.trycloudflare.com/mcp
  Header   : X-Auth-Token: <24-hour scoped key "launcher">
             (the master token is NOT shown; revoke anytime)
  ------------------------------------------------------------

Without --tunnel nothing is exposed to the internet — the launcher is a local-only startup. The pasted credential is a 24-hour mcp-scoped key (minted locally, revocable via POST /api/keys {"action":"revoke",...}).

stop-server.bat stops all three (REST, MCP, tunnel) in one go.

Available tools (16)

Documentation truncated — see the full README on GitHub.