Monitoring & Diagnostics

AI Assistant Access (MCP)

Let Cursor, Claude Code and other MCP-compatible AI assistants inspect your apps, servers, databases and metrics, and optionally deploy, roll back, restart, scale, query databases or manage cron — each capability its own toggle.

DeployOS ships a local MCP server so an AI coding assistant can answer "why is my app down?" or restart a stuck app, without you switching windows. Every capability beyond read access is off until you individually turn it on — enabling AI assistant access does not, by itself, grant write access to anything.

What it can do

Twelve read-only tools are always available the moment AI assistant access is on — nothing here can change anything:

list_apps / get_app — every app, or full detail on one (domains, build method, port, replicas, health path, repo/branch)
list_servers — every server DeployOS manages
list_deployments — recent deployments for a named app (each entry's ID works with rollback)
run_doctor — the 9-step Doctor diagnostic (DNS, ports, proxy, container, network, route, health, TLS, logs) against a named app
fetch_logs — recent logs for a named app, from the app itself or its reverse proxy
get_server_metrics / get_app_metrics — live CPU/RAM/disk for a server, and p50/p95/p99 latency + status-code breakdown for an app
list_env_var_keys — the env var names set on an app, never their values
list_databases / list_db_backups — every database, and the backup files already taken for one
list_templates — the one-click app template library

Everything past that is a separate, per-tool toggle in Settings — off by default:

Group	Tool	What it does
App lifecycle	Deploy an app	Fetches the latest commit (or rebuilds from the pinned image), publishes the route, and health-checks it — the same pipeline as clicking Deploy in DeployOS, including AI Deploy Guardrails and the pre-migration snapshot check
App lifecycle	Roll back an app	Rolls back to a previous deployment — instant if that deployment's image is still cached, otherwise rebuilds from that commit
App lifecycle	Restart an app	Restarts a named app's containers
App lifecycle	Scale an app	Changes a named app's replica count
App lifecycle	Deploy a template	Deploys a one-click template (Uptime Kuma, n8n, etc.) as a new app
Configuration	Set an env var	Sets a single env var on an app, leaving the rest untouched — doesn't itself restart the app
Databases	Run a database backup	Takes an on-demand backup of a database right now
Databases	Run a database query	Runs arbitrary SQL/commands against a database — can write or delete data, no undo beyond existing backups
Operations	Manage cron jobs	List, add, enable/disable/remove cron jobs on a server
Destructive	Tear down an app	Deletes a named app's containers, volumes, images and route — no undo

Nothing beyond this list is ever exposed, and a tool call for something you haven't turned on returns a clear "not enabled — turn it on in Settings" message rather than silently doing nothing or failing oddly. Every tool also carries standard MCP annotations (read-only, destructive, idempotent) so clients like Claude Code can show you accurate risk before calling one.

Setup — everything happens in the desktop app

There's no separate account, token, or credential entry for MCP. The server reads the exact same servers, apps and SSH credentials already configured in DeployOS, straight from your OS keychain — the same way the desktop app itself does. If you installed DeployOS the normal way, the MCP server binary is already sitting next to it — no Rust toolchain, no build step.

Open Settings → AI assistant access and switch it on. DeployOS shows you the exact path to the binary on your machine, already filled into a ready-to-paste config.
Add that to Cursor's or Claude Code's MCP config (typically a mcp.json or .cursor/mcp.json):
```
{
  "mcpServers": {
    "deployos": {
      "command": "/Applications/DeployOS.app/Contents/MacOS/mcp_server"
    }
  }
}
```
(Settings gives you the real path for your install — this is just what it looks like on a normal macOS install.)
Restart your assistant so it picks up the new server, then ask it something like "list my DeployOS apps" or "run Doctor on my-app."

If AI assistant access is off, the binary exits immediately with a message telling you where to turn it on — it won't silently do nothing.

Building from source instead (contributing to DeployOS itself)? A dev build only compiles the binary you ask for, so Settings will tell you to run npm run build:mcp from the project root first — the path only auto-fills once that binary actually exists on disk.

How deploy and rollback work headless

deploy_app and rollback_app stream live progress back into DeployOS's own UI, which normally needs a real, running desktop-app window under the hood. The MCP server runs headless (no window ever appears) — it builds a real app instance with its window forced invisible, gets a fully working handle without ever showing anything on screen, and that's what makes both possible here at all.

Privacy

Nothing about your servers, apps, or SSH keys is sent anywhere by enabling this — the MCP server talks to your AI assistant over local stdio (standard input/output on your own machine), the same transport Cursor and Claude Code use for every local MCP server. It's exactly as private as running a command in your terminal and pasting the output into a chat, except automated.

Running the Doctor

Firewall & SSH