How do I use vela-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vela-mcp what's the current CPU usage on the remote host?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

vela-mcp

by mikesplore

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Vela MCP Server

MCP (Model Context Protocol) server that exposes Vela RemotePC endpoints as tools, so AI clients (Claude Desktop, Cline, Cursor, Gemini, etc.) can control remote systems.

Architecture

The server supports two transport modes that share the same 150+ tool definitions (tools.py):

1. STDIO (single-tenant, per-process)

Each process is bound to one agent via environment variables. Run multiple agents by defining multiple entries in mcp_settings.json, each with its own env block.

MCP client config (cline_mcp_settings.json or claude_desktop_config.json):

{
  "mcpServers": {
    "vela-home": {
      "command": "/path/to/.venv/bin/mcp",
      "args": ["run", "vela_mcp/tools.py:mcp"],
      "cwd": "/path/to/vela-mcp",
      "env": {
        "VELA_API_URL": "https://vela.mikesplore.tech",
        "VELA_TOKEN": "<relay_secret>",
        "AGENT_ID": "agt_123"
      }
    },
    "vela-work": {
      "command": "/path/to/.venv/bin/mcp",
      "args": ["run", "vela_mcp/tools.py:mcp"],
      "cwd": "/path/to/vela-mcp",
      "env": {
        "VELA_API_URL": "https://vela.mikesplore.tech",
        "VELA_TOKEN": "<relay_secret>",
        "AGENT_ID": "agt_456"
      }
    }
  }
}

2. HTTP (multi-tenant, shared server)

A single server instance handles any number of agents. Create a scoped MCP connection with vela --mcp; it returns an opaque URL and a dedicated bearer credential:

MCP URL:        https://mcp.mikesplore.tech/mcp/c_8f4a...
Authentication: Bearer <mcp-credential>

The MCP credential is stored as a hash and can expire or be revoked independently of the Vela relay secret. The gateway resolves the connection to its agent and uses the relay secret internally. Neither agent_id nor relay_secret is accepted in the MCP URL.

Claude connectors select OAuth during setup. The gateway provides OAuth discovery, dynamic client registration, PKCE authorization, short-lived bearer access tokens, and rotating refresh tokens. During authorization, enter the MCP credential printed once by vela --mcp; supported clients can then renew access without asking for that credential again.

MCP tool safety

The gateway applies the same risk categories used by Vela’s assistant. Read-only tools execute immediately. Medium- and high-risk tools return a short-lived, single-use approval link and request_id instead of executing. Open the returned approval_url, approve once, then let the MCP client continue the exact pending request. The server claims and completes that request atomically, so duplicate continuations cannot execute the action twice. High-risk approvals also require the Vela ASSISTANT_ACTION_PIN when one was configured during connection creation.

Each MCP connection has a user-selected tool policy: strict (default) requires approval for medium/high-risk tools, read_only exposes only read-only tools, and open executes all exposed tools without MCP approval. Set MCP_TOOL_POLICY in the agent .env, or override one connection with vela --mcp --mcp-policy read_only.

Stdio mode also supports strict approvals. The first gated call starts a loopback-only approval page on 127.0.0.1, returns a one-time local link, and waits for the client to continue the request. The server never opens the browser automatically and the page is not reachable from the network. Set ASSISTANT_ACTION_PIN in the MCP environment if high-risk local approvals should require a PIN.

How multi-tenancy works

vela-mcp stores scoped MCP connection records. It extracts only an opaque connection ID and a dedicated MCP credential from each request, then resolves the agent server-side.
velavps (the relay server) enforces isolation: _verify_agent_access(agent_id, secret) rejects requests where the secret doesn't match the agent's registered secret, or where the agent belongs to another user.
150+ tools are untouched — they call vela_client.get/post/… which resolves to either the per-request or per-process client automatically.

Related MCP server: allcanuse-mcp

Quick Start

python -m vela_mcp.server

Server starts on http://0.0.0.0:8002 with the MCP endpoint at /mcp/{connection_id}.

Setup

Copy .env.example to .env
Set VELA_API_URL — your Vela relay VPS host (e.g. https://vela.mikesplore.tech)
For stdio mode: also set VELA_TOKEN (relay secret) and AGENT_ID
For HTTP mode: you only need VELA_API_URL and PORT; credentials come from the client

Run Script

./run.sh            # start the MCP server (HTTP/streamable transport)
./run.sh dev        # start the MCP Inspector (dev/testing UI)

Project Layout

vela_mcp/
  __init__.py
  config.py      # Settings (VELA_API_URL, VELA_TOKEN, AGENT_ID, PORT)
  client.py      # RelayConnection, VelaClient, per-request contextvar proxy
  server.py      # FastAPI app with scoped middleware at /mcp/{connection_id}
  tools.py       # 150+ MCP tool definitions (unchanged)

Development

.venv/bin/mcp dev vela_mcp/tools.py:mcp

Requirements

Python >= 3.10
mcp >= 1.0.0
fastapi >= 0.110.0
httpx >= 0.27.0
pydantic-settings >= 2.0.0
uvicorn >= 0.30.0

Available Tools

183 tools

active_windowA

Read-onlyIdempotent

Get the currently focused window title and app path.

Inputs: no named parameters.

audio_devicesA

Read-onlyIdempotent

List available audio sinks and sources.

Inputs: no named parameters.

beep_audioA

Play a simple notification beep sound.

Inputs: no named parameters.

cancel_jobA

Cancel a scheduled task.

Inputs: task_id (required).

check_alert_statusA

Read-onlyIdempotent

Check the monitoring system status: whether spike alerts and daily summaries are scheduled, alerts today, and recipient email from .env. No email input needed — reads RECIPIENT_EMAIL from .env.

Inputs: no named parameters.

check_package_installedB

Read-onlyIdempotent

Check whether a package is installed (apt/dnf/pacman).

Inputs: name (required).

check_portA

Read-onlyIdempotent

Find what process is listening on a TCP port on this machine. Use when the user asks what service/app uses a port, what's on port X, or if a port is open (e.g. 8765 for the local Vela API). Returns PID, process name, and command line.

Inputs: port (required).

check_updatesA

Read-onlyIdempotent

Check for available system updates.

Inputs: no named parameters.

check_vnstat_statusA

Read-onlyIdempotent

Check if vnstat is installed, its version, and which network interfaces it's monitoring.

Inputs: no named parameters.

clear_cacheA

Clear /tmp and user cache directories.

Inputs: no named parameters.

clear_clipboardA

Clear the clipboard contents.

Inputs: no named parameters.

clear_notificationsA

Clear all desktop notifications.

Inputs: no named parameters.

close_applicationA

Close a desktop/GUI application. Accepts the same friendly names and .desktop resolution as open_application (e.g. 'Chrome', 'firefox'). Matches running processes by exec binary and process name.

Inputs: name (required).

close_windowB

Close a window by window ID.

Inputs: window_id (required).

compose_statusB

Read-onlyIdempotent

List services from a Docker Compose project.

Inputs: project, project_directory.

connect_wifiC

Connect to a WiFi network.

Inputs: ssid (required), password.

count_toolsA

Read-onlyIdempotent

Count how many assistant tools are available on this host. Use when the user asks how many tools/capabilities/commands you have, or how many things you can do.

Inputs: no named parameters.

delete_pathB

Destructive

Delete a file or directory.

Inputs: path (required).

disable_micA

Mute the default microphone source.

Inputs: no named parameters.

disable_webcamA

Disable the webcam by unloading the kernel module.

Inputs: no named parameters.

disconnect_wifiB

Disconnect from the current WiFi network.

Inputs: no named parameters.

display_recordB

Read-onlyIdempotent

Record a short screen clip and return MP4 as base64.

Inputs: duration_seconds (required).

display_screenshotA

Read-onlyIdempotent

Capture the current screen with flameshot to ~/Pictures and return it to the client as base64 image data (compressed for relay delivery when large). The AI model only receives a success confirmation — the image is delivered to the user interface separately.

Inputs: no named parameters.

download_fileA

Read-onlyIdempotent

Download a file from the local filesystem and send it to the user interface. Images are shown in the UI (not to the AI model) — you only get a success confirmation with path/size. Files larger than the configured limit are rejected with size details; do not retry the same path. Use for transferring a file the user asked to see or receive, not for reading file contents yourself.

Inputs: path (required).

enable_micA

Unmute the default microphone source.

Inputs: no named parameters.

enable_webcamA

Enable the webcam by loading the kernel module.

Inputs: no named parameters.

gatekeeper_block_projectA

Manually block a Gatekeeper client project (gates their site/API). Requires slug and a non-empty reason. Confirmation gate applies.

Inputs: slug (required), reason (required).

gatekeeper_check_certificate_statusA

Read-onlyIdempotent

Check whether an SSL certificate is installed for a domain.

Inputs: domain (required).

gatekeeper_check_image_statusA

Read-onlyIdempotent

Wizard helper: check whether an image is available locally before attempting container creation.

Inputs: image (required).

gatekeeper_containers_wizard_contextA

Read-onlyIdempotent

Wizard helper: fetch Docker container-creation context (networks + internal network info).

Inputs: no named parameters.

gatekeeper_containers_wizard_ports_checkB

Read-onlyIdempotent

Wizard helper: check whether host ports are already in use on the Docker host.

Inputs: hostPorts (required).

gatekeeper_containers_wizard_validateB

Read-onlyIdempotent

Wizard helper: validate and normalize a CreateContainerRequest without applying changes.

Inputs: no named parameters.

gatekeeper_create_containerA

Create and start a new Docker container with custom configuration. DEPLOYMENT ORDER: This is step 1 of 4 — do this first. Requires image. Optional: name, projectSlug, ports, env, network, volumes, restartPolicy. If the user provides .env variables, pass them in the env field. If the user says the env vars are already in a local .env file on the Docker host, prefer passing envFilePath (absolute path) so Gatekeeperd can load it server-side. After creation, verify the container is running before proceeding to project creation.

Inputs: image (required), env, name, ports, +5 more.

gatekeeper_create_projectA

Create a new Gatekeeper project registration. PREREQUISITE: Docker container must already exist and be running (use gatekeeper_create_container first). DEPLOYMENT ORDER: This is step 2 of 4. 1) gatekeeper_check_image_status → gatekeeper_create_container → ensure running 2) gatekeeper_create_project (this step) 3) gatekeeper_nginx_wizard_context → gatekeeper_nginx_enable 4) gatekeeper_install_certificate. Use for onboarding new clients.

Inputs: name (required), slug (required), type (required), domain (required), +7 more.

gatekeeper_delete_containerB

Destructive

Delete a container permanently.

Inputs: name (required).

gatekeeper_delete_imageA

Destructive

Delete a Docker image from the local Docker host.

Inputs: image (required), tag, force.

gatekeeper_delete_projectA

Destructive

Archive a Gatekeeper project (soft delete). Preserves payments and audit log. Use when removing a client while keeping historical data.

Inputs: slug (required).

gatekeeper_get_containerA

Read-onlyIdempotent

Get details for a single container by name or ID prefix.

Inputs: name (required).

gatekeeper_get_container_healthB

Read-onlyIdempotent

Get container health/running state.

Inputs: name (required).

gatekeeper_get_projectA

Read-onlyIdempotent

Get one Gatekeeper project with payment history and audit log. Use when the user asks about a specific client site or slug.

Inputs: slug (required).

gatekeeper_get_project_auditA

Read-onlyIdempotent

Get audit log for a specific project.

Inputs: slug (required).

gatekeeper_initialize_paymentA

Generate a Paystack payment link for a project. Requires slug and email. Creates a pending payment and returns a checkout URL.

Inputs: slug (required), email (required).

gatekeeper_install_certificateA

Install an SSL certificate for a domain using certbot. DEPLOYMENT ORDER: This is step 4 of 4 — do this last. PREREQUISITE: nginx site must be enabled (use gatekeeper_nginx_enable first). Requires domain and email. This completes the deployment.

Inputs: email (required), domain (required).

gatekeeper_list_auditA

Read-onlyIdempotent

Recent Gatekeeper audit log entries across all projects (block/unblock/payments).

Inputs: limit.

gatekeeper_list_certificatesA

Read-onlyIdempotent

List installed SSL certificates found under /etc/letsencrypt/live.

Inputs: no named parameters.

gatekeeper_list_containersA

Read-onlyIdempotent

List all Docker containers visible to Gatekeeperd on the host.

Inputs: no named parameters.

gatekeeper_list_networksA

Read-onlyIdempotent

List Docker networks.

Inputs: no named parameters.

gatekeeper_list_overdueA

Read-onlyIdempotent

List active Gatekeeper projects past their due date, sorted by days overdue. Use for payment triage — who is late and when auto-block kicks in.

Inputs: no named parameters.

gatekeeper_list_paymentsA

Read-onlyIdempotent

List payments across all Gatekeeper projects with optional filters: status (pending/success/failed/abandoned/reversed), project_slug, from/to dates, limit, offset.

Inputs: to, limit, offset, status, +2 more.

gatekeeper_list_projectsA

Read-onlyIdempotent

List all Gatekeeper client projects (slug, name, domain, status, due date, amount due). Use for billing/access overview across hosted clients.

Inputs: no named parameters.

gatekeeper_nginx_disableA

Disable (unlink) an nginx site without removing the config file.

Inputs: slug (required).

gatekeeper_nginx_enableA

Generate and enable an nginx site config for a project. PREREQUISITE: Project must exist and container must be running. DEPLOYMENT ORDER: This is step 3 of 4. Use gatekeeper_nginx_wizard_context first to fetch project details and validate. After enabling, proceed to gatekeeper_install_certificate for SSL.

Inputs: slug (required).

gatekeeper_nginx_removeA

Destructive

Remove an nginx site completely (both sites-available file and sites-enabled symlink).

Inputs: slug (required).

gatekeeper_nginx_statusB

Read-onlyIdempotent

Check if a project has an nginx site configured and enabled, and whether SSL is set up.

Inputs: slug (required).

gatekeeper_nginx_validateB

Wizard helper: validate nginx enable inputs and return a config preview without applying changes.

Inputs: slug (required).

gatekeeper_nginx_wizard_contextA

Read-onlyIdempotent

Wizard helper: fetch project + nginx context to drive a step-by-step UI (status, container hints, certificate options).

Inputs: slug (required).

gatekeeper_pull_imageC

Pull a Docker image from a registry.

Inputs: image (required), tag, pullViaCli.

gatekeeper_remove_certificateB

Destructive

Remove an SSL certificate for a domain.

Inputs: domain (required).

gatekeeper_restart_containerC

Restart a container.

Inputs: name (required).

gatekeeper_revenue_reportB

Read-onlyIdempotent

Gatekeeper revenue summary: total this month, last month, and monthly breakdown. Optional input: period (default month), months (default 6).

Inputs: months, period.

gatekeeper_start_containerC

Start a stopped container.

Inputs: name (required).

gatekeeper_stop_containerB

Stop a running container.

Inputs: name (required).

gatekeeper_unblock_projectA

Manually unblock a Gatekeeper client project after payment or agreement. Requires slug and a non-empty reason. Confirmation gate applies.

Inputs: slug (required), reason (required).

gatekeeper_update_projectA

Update Gatekeeper project fields for an existing client project. PATCH semantics: provide slug to target the project plus ONLY the fields the user asked to change — every body field is optional but at least one is required. Editable fields: name, domain, containerName, type (frontend|backend), clientName, clientEmail, amountDue (number), currency (e.g. KES/USD), dueDate (YYYY-MM-DD, or null to clear), gracePeriodDays (integer). Do NOT send fields the user did not ask to change.

Inputs: slug (required), name, type, domain, +7 more.

get_batteryA

Read-onlyIdempotent

Battery percentage, plugged state, and remaining seconds.

Inputs: no named parameters.

get_boot_errorsA

Read-onlyIdempotent

Recent error-level journal entries from the current boot.

Inputs: lines (required).

get_container_logsB

Read-onlyIdempotent

Recent logs from a Docker container.

Inputs: lines (required), name_or_id (required).

get_container_statusA

Read-onlyIdempotent

Detailed status for one Docker container. Use FIRST when asked if a container is running.

Inputs: name_or_id (required).

get_currently_playing_songB

Read-onlyIdempotent

Current playback status, title, artist, album, album art URL, and position.

Inputs: no named parameters.

get_device_infoA

Read-onlyIdempotent

High-level device identity: laptop model (e.g. ThinkPad X1 Carbon Gen 9), vendor (e.g. Lenovo), OS distro, kernel, architecture, hostname. Use when the user asks 'what device/laptop/computer is this'. For deeper hardware specs use get_system_info; for OS-only details use get_system_os.

Inputs: no named parameters.

get_directory_treeB

Read-onlyIdempotent

Get directory tree structure for folder navigation.

Inputs: path (required), max_depth (required).

get_disk_usageA

Read-onlyIdempotent

Disk space usage: how much free and used space each mounted partition has. Use when the user asks how much space is left or available. Do NOT use for partition layout or filesystem type — use get_system_disk for that.

Inputs: no named parameters.

get_display_brightnessA

Read-onlyIdempotent

Get the current screen brightness.

Inputs: no named parameters.

get_docker_infoA

Read-onlyIdempotent

Check whether Docker is installed and the daemon is running.

Inputs: no named parameters.

get_firewall_statusA

Read-onlyIdempotent

Get ufw firewall status when installed.

Inputs: no named parameters.

get_logsA

Read-onlyIdempotent

Get the last N lines of a systemd service log.

Inputs: lines (required), service (required).

get_monitor_stateA

Read-onlyIdempotent

Check whether the monitor is currently on or off. Use before toggling monitor state if unsure of the current state.

Inputs: no named parameters.

get_network_ipA

Read-onlyIdempotent

Local and public IP addresses.

Inputs: no named parameters.

get_network_locationA

Read-onlyIdempotent

Public IP with geo-location: city, region, country, timezone, ISP, coordinates.

Inputs: no named parameters.

get_power_profileA

Get the current power profile (performance, balanced, power-saver).

Inputs: no named parameters.

get_resolutionA

Read-onlyIdempotent

Get the current display resolution and refresh rate.

Inputs: no named parameters.

get_service_statusA

Read-onlyIdempotent

Check whether a specific systemd service is running, failed, or stopped. Use FIRST when the user asks if a service is up/running/active. Do NOT start or restart the service to answer a status question.

Inputs: name (required), scope (required).

get_snapshotA

Read-onlyIdempotent

Live system metrics snapshot: current CPU load, RAM usage, GPU usage, disk I/O rates, network I/O rates, temperatures, fan speeds, battery level, top processes. Use for 'how is my PC doing' or real-time status. Do NOT use for static hardware specs — use get_system_info for that.

Inputs: no named parameters.

get_system_biosB

Read-onlyIdempotent

BIOS vendor, version, release date, and motherboard.

Inputs: no named parameters.

get_system_configA

Read-onlyIdempotent

Get system configuration (home directory, username).

Inputs: no named parameters.

get_system_cpuA

Read-onlyIdempotent

Static CPU specs: model name, core/thread counts, base clock, architecture. Use when the user asks WHAT CPU they have. Do NOT use for live CPU load — use monitor_cpu for current usage.

Inputs: no named parameters.

get_system_diskA

Read-onlyIdempotent

Static disk layout: partition names, mount points, filesystem types, and total sizes. Use when the user asks about drive partitions or disk setup. Do NOT use for free space or usage stats — use get_disk_usage for that.

Inputs: no named parameters.

get_system_gpuA

Read-onlyIdempotent

Static GPU info: GPU device names and models. Use when the user asks WHAT GPU they have. Do NOT use for live GPU load — use monitor_gpu for that.

Inputs: no named parameters.

get_system_infoA

Read-onlyIdempotent

Static hardware specs bundle: CPU model, RAM capacity, GPU model, disk partitions, OS version, USB devices, monitor config, and BIOS. Use when the user wants to know WHAT their machine is made of. Do NOT use for live usage — use get_snapshot for live metrics.

Inputs: no named parameters.

get_system_monitorsA

Read-onlyIdempotent

Static monitor hardware info: display names, resolutions, refresh rates. Use when the user asks about their monitor specs. Do NOT use to check if the monitor is on/off — use get_monitor_state for that.

Inputs: no named parameters.

get_system_osA

Read-onlyIdempotent

OS identity: distro name, kernel version, hostname, current username. Use for OS/kernel-specific questions. For a full device summary including hardware vendor and model, use get_device_info instead.

Inputs: no named parameters.

get_system_ramA

Read-onlyIdempotent

Static RAM capacity: total installed memory and swap size. Use when the user asks how much RAM they have. Do NOT use for live memory usage — use monitor_ram for that.

Inputs: no named parameters.

get_system_statsA

Read-onlyIdempotent

Get current system stats on demand: CPU usage, memory, vnstat network (today + month), top processes, uptime. Use when the user asks 'how's my system', 'give me stats', 'show system status'.

Inputs: no named parameters.

get_system_usbB

Read-onlyIdempotent

Connected USB devices.

Inputs: no named parameters.

get_top_processesA

Read-onlyIdempotent

Top resource-consuming processes ranked by CPU and memory usage. Use when the user asks what is slowing down or eating up their system. Do NOT use to find a specific process by name — use list_processes for that.

Inputs: no named parameters.

get_uptimeA

Read-onlyIdempotent

Get system uptime: how long the laptop has been running since last boot, returned as seconds, minutes, hours, days, and a human-readable formatted string.

Inputs: no named parameters.

get_vnstat_dataA

Read-onlyIdempotent

Get network usage from vnstat for a specific period. period: 'day' (today — default), 'month' (this month), 'hour' (current hour). Use when the user asks about their data usage or bandwidth.

Inputs: period.

get_volumeA

Read-onlyIdempotent

Current master volume level and mute state.

Inputs: no named parameters.

get_vpn_statusA

Read-onlyIdempotent

Check whether a VPN interface or NetworkManager VPN connection is active.

Inputs: no named parameters.

get_wifi_statusA

Read-onlyIdempotent

Current WiFi connection state only: connected/disconnected, active SSID, signal strength. Use when the user asks if they are connected or what network they are on. Do NOT use to browse nearby networks — use list_wifi_networks for that.

Inputs: no named parameters.

health_checkC

Read-onlyIdempotent

Probe an HTTP(S) URL and report whether it responds.

Inputs: url (required).

is_process_runningA

Read-onlyIdempotent

Check whether a process or app is currently running by name. Use FIRST when asked if an application/process is open — do NOT launch it just to check.

Inputs: name (required).

kill_processB

Destructive

Kill a process by PID.

Inputs: pid (required).

kill_process_by_nameB

Destructive

Kill all processes matching a name.

Inputs: name (required).

list_bluetooth_devicesA

Read-onlyIdempotent

List connected Bluetooth devices and paired devices available to connect.

Inputs: no named parameters.

list_docker_containersA

Read-onlyIdempotent

List Docker containers. Use when the user asks what containers are running or to find a container by name/image.

Inputs: all (required), filter.

list_failed_servicesB

Read-onlyIdempotent

List failed systemd units from the current boot.

Inputs: scope (required).

list_filesC

Read-onlyIdempotent

List files and directories at a path.

Inputs: path (required).

list_installed_applicationsA

Read-onlyIdempotent

List installed desktop applications from this machine (.desktop entries): display name, desktop id, exec binary. Use when the user asks what apps are installed, what browser/IDE they have, or before opening an ambiguous app name.

Inputs: filter.

list_jobsB

Read-onlyIdempotent

List all scheduled tasks.

Inputs: no named parameters.

list_notificationsA

List all desktop notification history system-wide (all apps). Use when the user asks to see recent notifications or missed alerts.

Inputs: no named parameters.

list_processesA

Read-onlyIdempotent

Full list of all running processes with PIDs. Use when the user wants to find a specific process by name or get a PID to kill. Do NOT use to see what is consuming the most resources — use get_top_processes for that.

Inputs: no named parameters.

list_servicesA

Read-onlyIdempotent

List systemd services and their status. Use filter to narrow results and scope=system|user|all for system vs user units (Vela runs as user services). Do NOT use to answer whether one specific service is running — use get_service_status instead.

Inputs: scope (required), filter.

list_timersA

Read-onlyIdempotent

List systemd timers and when they next run.

Inputs: scope (required), filter.

list_toolsA

Read-onlyIdempotent

List all assistant tool names available on this host, optionally filtered by a search term. Use when the user asks what tools/capabilities/commands you have, what you can do, or whether a specific capability exists.

Inputs: filter.

list_wifi_networksA

Read-onlyIdempotent

Scan and list all nearby WiFi networks with SSID and signal strength. Use when the user wants to see what networks are available nearby, not just their current connection.

Inputs: no named parameters.

lock_screen_displayA

Lock the screen via the display manager (fast path, no fallbacks). Prefer lock_screen_security unless you specifically need the display-manager lock.

Inputs: no named parameters.

lock_screen_securityA

Lock the screen with multiple fallbacks (most reliable). Use this when the user says 'lock', 'lock the screen', or 'lock my computer'. Prefer this over lock_screen_display.

Inputs: no named parameters.

login_historyA

Read-onlyIdempotent

Get recent login events from system auth logs.

Inputs: no named parameters.

logout_userA

Log out the current user session.

Inputs: no named parameters.

make_directoryA

Create a new directory.

Inputs: path (required).

minimize_windowC

Minimize a window by window ID.

Inputs: window_id (required).

monitor_battery_healthA

Read-onlyIdempotent

Get detailed battery health information (cycle count, capacity, health percent).

Inputs: no named parameters.

monitor_cpuA

Read-onlyIdempotent

Live CPU usage: current load percentage overall and per core. Use when the user asks how loaded their CPU is right now. Do NOT use for CPU specs or model — use get_system_cpu for that.

Inputs: no named parameters.

monitor_disk_ioB

Read-onlyIdempotent

Per-disk I/O rates.

Inputs: no named parameters.

monitor_fansC

Read-onlyIdempotent

Fan speed sensor readings.

Inputs: no named parameters.

monitor_gpuA

Read-onlyIdempotent

Live GPU usage: current GPU utilization percentage and VRAM used. Use when the user asks how hard their GPU is working right now. Do NOT use for GPU model info — use get_system_gpu for that.

Inputs: no named parameters.

monitor_network_ioA

Read-onlyIdempotent

Network I/O rates per interface.

Inputs: no named parameters.

monitor_offA

Turn the monitor/screen off (blank the display). Use when the user says 'turn off the screen', 'blank the display', or similar.

Inputs: no named parameters.

monitor_onA

Turn the monitor/screen back on. Use when the user says 'turn on the screen', 'wake the display', or similar.

Inputs: no named parameters.

monitor_ramA

Read-onlyIdempotent

Live memory usage: how much RAM and swap is currently used vs free. Use when the user asks how much memory is being used right now. Do NOT use for total RAM capacity — use get_system_ram for that.

Inputs: no named parameters.

monitor_temperaturesC

Read-onlyIdempotent

Sensor temperature readings.

Inputs: no named parameters.

mute_audioA

Mute or unmute the master audio channel.

Inputs: muted (required).

next_trackA

Skip to the next media track.

Inputs: no named parameters.

open_applicationA

Open a desktop/GUI application. Accepts friendly names ('Chrome', 'firefox'), .desktop ids ('google-chrome.desktop'), or exec binaries — resolved against installed .desktop entries on this PC. Use list_installed_applications when unsure of the exact name.

Inputs: args (required), name (required).

open_pathA

Open a file or directory with the default system application.

Inputs: path (required).

pair_bluetooth_deviceC

Pair with a Bluetooth device.

Inputs: address (required).

ping_hostB

Read-onlyIdempotent

Ping a host and return packet loss and average RTT.

Inputs: host (required), count (required).

press_keyboard_keysB

Press one or more keyboard keys or shortcuts.

Inputs: keys (required).

previous_trackA

Skip to the previous media track.

Inputs: no named parameters.

read_clipboardA

Read-onlyIdempotent

Read the current clipboard text.

Inputs: no named parameters.

read_notificationsA

Read only the notifications that were sent by this agent in the current session. Do NOT use for system-wide notification history — use list_notifications for that.

Inputs: no named parameters.

rename_pathC

Rename or move a file or directory.

Inputs: to (required), from_path (required).

restart_containerC

Restart a Docker container.

Inputs: name_or_id (required).

restart_serviceB

Restart a systemd service. Use only when the user asks to restart/fix it — not to check status.

Inputs: name (required), scope (required).

run_job_nowB

Trigger a scheduled task immediately.

Inputs: task_id (required).

run_updateA

Run a full system update (requires confirmation).

Inputs: confirm (required).

schedule_jobC

Schedule a command at a specific time or on a cron schedule.

Inputs: args (required), run_at (required), command (required), recurring.

search_and_playA

Search Spotify for a song and immediately play it. If no active device is available, Vela opens the local Spotify app and registers this PC as a playback device before retrying. Use when the user wants to hear a specific song.

Inputs: query (required), device_id.

search_filesA

Read-onlyIdempotent

Search files and directories by name under allowed directories. Prefer path under the user home (e.g. /home/). If path is / or omitted, search is automatically limited to configured allowed_base_dirs.

Inputs: query (required), path.

seek_mediaA

Seek media playback to a position in seconds.

Inputs: seconds (required).

send_daily_summary_nowA

Send the daily system summary email right now. Includes CPU, memory, vnstat network stats, top processes. Goes to RECIPIENT_EMAIL from .env — no email prompt.

Inputs: no named parameters.

send_notificationC

Send a desktop notification.

Inputs: title (required), message (required), urgency, app_name.

send_push_notificationA

Send a push notification to the user's registered mobile devices.

Inputs: body (required), title (required), data.

send_test_emailA

Send a test spike alert email to RECIPIENT_EMAIL (from .env) to verify Resend is working. Always sends regardless of CPU/memory. No email input needed.

Inputs: no named parameters.

send_test_spike_alertA

Manually check CPU/memory and send an alert email if thresholds are exceeded. Email goes to RECIPIENT_EMAIL from .env (no prompt). Optional: cpu_threshold (default 80%), memory_threshold (default 85%).

Inputs: cpu_threshold, memory_threshold.

set_display_brightnessC

Set the screen brightness.

Inputs: value (required).

set_night_lightA

Enable or disable night light and set colour temperature.

Inputs: enabled (required), temperature (required).

set_output_deviceC

Switch the default audio output device.

Inputs: device_id (required).

set_power_profileC

Set the power profile.

Inputs: profile (required).

set_volumeA

Set audio volume to a specific percentage.

Inputs: value (required).

speed_testA

Run a network speed test (download, upload, ping).

Inputs: no named parameters.

spotify_authA

Start Spotify account linking. Returns an auth URL the user must open in a browser to sign in and approve access. After approving, Spotify redirects to the configured callback URL and Vela finishes linking automatically — the browser should show a success or failure page.

Inputs: no named parameters.

spotify_callbackA

Legacy/manual completion of Spotify linking with an authorization code. Prefer the automatic browser redirect to /spotify/callback; only use this if the redirect could not finish linking.

Inputs: code (required).

spotify_devicesA

Read-onlyIdempotent

Get list of available Spotify playback devices (speakers, computers, phones). Use when the user asks what devices are available for playback.

Inputs: no named parameters.

ssh_sessionsA

Read-onlyIdempotent

List active SSH sessions.

Inputs: no named parameters.

start_containerA

Start a Docker container. Check status first unless the user explicitly asked to start it.

Inputs: name_or_id (required).

start_serviceA

Start a systemd service. Use get_service_status first when the user asks if it is running; only start when they ask to start it or it is down and they want it fixed.

Inputs: name (required), scope (required).

stop_containerB

Stop a Docker container.

Inputs: name_or_id (required).

stop_serviceC

Stop a systemd service.

Inputs: name (required), scope (required).

sync_timeA

Sync the system clock via NTP.

Inputs: no named parameters.

toggle_bluetoothA

Enable or disable the Bluetooth radio.

Inputs: enabled (required).

toggle_play_pauseA

Toggle media playback on or off.

Inputs: no named parameters.

toggle_wifiB

Enable or disable the WiFi radio.

Inputs: enabled (required).

type_keyboardA

Type text at the current focused input.

Inputs: text (required).

unpair_bluetooth_deviceC

Unpair a Bluetooth device.

Inputs: address (required).

unzip_pathB

Extract a zip archive to a destination directory.

Inputs: path (required), destination (required).

upload_fileC

Destructive

Upload a file to a destination path.

Inputs: path (required), file_base64 (required).

volume_downB

Decrease the master volume by a step.

Inputs: step (required).

volume_upB

Increase the master volume by a step.

Inputs: step (required).

webcam_snapshotA

Capture a webcam image and return it as base64 PNG.

Inputs: no named parameters.

write_clipboardA

Write text to the clipboard.

Inputs: text (required).

zip_pathsC

Create a zip archive from files and directories.

Inputs: paths (required), output (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-09-18 16:00 across 183 tools

Disambiguation4/5

Descriptions are unusually careful with cross-references ('Do NOT use X for Y'), which makes most tools easy to tell apart. Still, some clusters overlap enough to cause misselection, such as Docker container tools vs. Gatekeeper container tools, and lock_screen_display vs. lock_screen_security.

Naming Consistency4/5

The overwhelming majority of tools use a clear snake_case verb_noun pattern (list_, get_, set_, monitor_, start_, stop_, etc.). A few outliers like audio_devices, active_window, login_history, and health_check break the pattern but do not make the set chaotic.

Tool Count1/5

183 tools is an extreme count for any MCP server, far beyond the 50+ threshold for a low score. Even with a broad all-in-one device-management scope, this volume creates heavy context overhead and makes tool selection expensive.

Completeness4/5

Within the domains the server targets, coverage is quite thorough: files, processes, services, Docker, Gatekeeper deployment, media, notifications, and network monitoring all have lifecycle-oriented operations. Minor gaps exist, such as no Compose up/down, no per-PID process details beyond listing, and no explicit payment-success recording, but these are workable.

Maintenance

ActivityStale

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
Backtest360A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
https://mcp.backtest360.com/mcp
Node Command
io.github.huseyincig
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
File Systems Shell Access Browser Automation
1
https://mcp.nodecommand.app/mcp
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp

Related MCP Servers

mcp-vnc
OS Automation App Automation Virtualization
hrrrsn
A
license
A
quality
D
maintenance
An MCP server that allows AI agents to remotely control Windows, Linux, and macOS systems via VNC. It provides tools for mouse and keyboard interaction, text input, and screen capturing.
Updated 5 days ago (2026-11-05 23:10 UTC)
6
404 npm
61
MIT
allcanuse-mcp
OS Automation Command Line Developer Tools
ra1nyxin
A
license
Not graded
quality
D
maintenance
A MCP server for Windows/Linux that provides 90+ tools enabling AI assistants to systematically manage local systems, including system probing, command execution, file editing, network diagnostics, and more.
Updated 6 months ago (2026-05-15 15:51 UTC)
13
MIT
rustdesk-mcp
Shell Access File Systems OS Automation
zsunny6658
A
license
Not graded
quality
D
maintenance
MCP server that enables AI agents to control remote machines via RustDesk, supporting device management, remote shell commands, file operations, power controls, and screen interaction.
Updated 3 months ago (2026-08-09 05:30 UTC)
MIT
PC Controller MCP Server
Shell Access File Systems OS Automation
rayss868
A
license
A
quality
C
maintenance
Enables AI assistants to control Windows PCs by executing shell commands, managing files, capturing screenshots, and monitoring system information through a comprehensive set of MCP tools.
Updated 2 months ago (2026-09-09 02:53 UTC)
18
1
MIT

Vela MCP Server

Architecture

1. STDIO (single-tenant, per-process)

2. HTTP (multi-tenant, shared server)

MCP tool safety

How multi-tenancy works

Quick Start

Setup

Run Script

Project Layout

Development

Requirements

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-vnc

allcanuse-mcp

rustdesk-mcp

PC Controller MCP Server