# Server Agent — Real-World Recipes

Practical prompts for common DevOps tasks once Server Agent is connected to
your AI client (Claude Desktop, Claude Code, Cursor, Cline, Zed). Each
recipe shows the **exact prompt** to type, **what tool fires** behind the
scenes, and **what to expect**.

> **Connecting first?** See [connect.md](connect.md). Already connected?
> Read on.

---

## How prompting works

You don't say tool names. You describe the outcome you want, and the AI
client routes through the right MCP tool. Two prompt patterns to remember:

| Pattern | Why use it |
|---|---|
| `"on the server, ..."` or `"use server-agent to ..."` | Explicit — tells Claude this is a remote VPS task, not a local file edit |
| Absolute paths (`/home/user/site/file.php`) | Skips workspace lookup; safest when you have no workspaces registered |

You can mix these, e.g. *"On the server, tail the last 100 lines of
`/var/log/nginx/error.log`."*

---

## Recipe 1 — Morning health check

**Scenario:** You log in, you want a "what's the state of my server" overview.

**Prompt:**
> *"Run a health check on the server and tell me anything I should worry about."*

**What happens:** `health_check` tool fires. Returns PHP version, disk
usage %, git branch + last commit, queue status, recent error count from
log files. Claude reads it and surfaces only the non-OK signals — e.g.
*"disk is at 87%, that's a yellow flag. Everything else is green."*

**Variant — focused on a specific concern:**
> *"Check disk usage and SSL cert expiry on ai.voxacade.com."*

This fires `disk_analyze` + `ssl_check`. Claude returns a short summary
plus the concrete numbers.

---

## Recipe 2 — Deploy the latest from main

**Scenario:** You merged a PR, time to ship.

**Prompt:**
> *"Take a backup, pull latest from main, run composer install, clear caches, then tail the error log for 30 seconds to make sure nothing exploded."*

**What happens:** Five tools chain in order:
1. `backup_create` — tar.gz of project root (excludes vendor/node_modules/.git)
2. `bash_execute` — `git pull origin main`
3. `bash_execute` — `composer install --no-dev --optimize-autoloader`
4. `bash_execute` — `php artisan cache:clear && php artisan config:cache` (or framework equivalent)
5. `log_tail` — most recent error log

Claude pauses on each step and asks for approval if you've left destructive
tools as "Needs approval" in the connector settings.

**Variant — with migrations:**
> *"Deploy: backup, git pull, composer install, php artisan migrate --force, restart php-fpm if available, tail log."*

(`service_control` may be unavailable on cPanel — Claude will tell you
and skip that step gracefully.)

---

## Recipe 3 — Debug a 500 error

**Scenario:** Site is throwing 500s. You don't know why.

**Prompt:**
> *"Something just broke on the server. Find the most recent error in the logs and tell me the file and line number."*

**What happens:**
1. `logs_list` — discovers all recent log files (Laravel, nginx, apache, php-fpm)
2. `log_tail` — pulls the last ~150 lines of the most-recently-modified one
3. Claude parses the stack trace, identifies the file:line
4. (Often) `file_read` — opens the file at that line so you can see the actual code

**Variant — narrow it down by time:**
> *"There's been a 500 in the last 10 minutes. Find it and explain what's wrong."*

Claude filters log entries by timestamp and summarizes the root cause.

---

## Recipe 4 — Database inspection

**Scenario:** Need to check production DB without SSH.

**Prompt:**
> *"On the server, query the database for the 5 largest tables by row count."*

**What happens:** `db_query` fires with a read-only `SELECT` against
`information_schema`. (The tool is hard-locked to read-only —
SELECT/SHOW/DESCRIBE/EXPLAIN only. No `UPDATE`, no `DELETE`, no `DROP`.)

**Variant — finding a specific record:**
> *"Show me the user record for email 'foo@bar.com' (just safe fields, no password hashes)."*

Claude writes the SELECT, reviews it for safety before submitting, and
returns the result.

---

## Recipe 5 — Switch environments before testing

**Scenario:** You want to swap `.env` from production to staging
to reproduce a bug, then back.

**Prompt:**
> *"List the saved env snapshots, then switch to staging."*

**What happens:**
1. `envs_list` — shows all saved `.env` snapshots for the project
2. `envs_switch` with `id=staging` — replaces the active `.env` (auto-backs up the current one first)

Then debug. When done:
> *"Switch back to production env."*

---

## Recipe 6 — Rollback a botched edit

**Scenario:** You (or Claude) wrote to a file and broke something.

**Prompt:**
> *"Show me the last 5 file backups, I want to roll back the most recent edit to api.php."*

**What happens:**
1. `rollback_list` — shows all auto-backups created when files were written, with timestamps + sizes
2. Claude identifies the most recent backup of `api.php`
3. `rollback_restore` with that backup's filename — restores it (creating a new backup of the current broken version first, so you can re-apply if you change your mind)

Every `file_write` and `bash_execute` that modifies files creates a backup
automatically. You're never one mistake from disaster.

---

## Recipe 7 — Save knowledge for next session

**Scenario:** You just discovered your prod DB uses port 3307 (not the
default 3306) and your staging server has a custom SSL provisioning quirk.
You don't want to re-explain this every conversation.

**Prompt:**
> *"Save a knowledge entry: 'Production DB on port 3307. Staging uses Let's Encrypt with auto-renew via /etc/cron.d/le-renew. Don't run certbot manually.' Tag it with deploy, ssl, db."*

**What happens:** `knowledge_save` writes the entry to the project's
knowledge store. **Persists across sessions** — next time you start a new
chat, ask:

> *"What do I know about this project?"*

`knowledge_get` fires, Claude pulls those entries, and your context is
loaded without re-typing.

---

## Recipe 8 — Security audit before launch

**Scenario:** You're about to make a project public. Want a quick safety pass.

**Prompt:**
> *"Audit the htaccess files on the server and check the SSL cert. Flag anything risky."*

**What happens:**
1. `htaccess_audit` — scans every `.htaccess` for: directory listing
   enabled, `display_errors=On`, missing security headers, etc.
2. `ssl_check` — verifies cert validity, expiry days remaining, issuer
3. Claude summarizes risks ordered by severity

**Variant — deeper scan:**
> *"Check disk usage for any unexpectedly large files (potential leftover dumps or rogue uploads)."*

`disk_analyze` lists top 20 largest dirs and top 15 largest files. Often
surfaces forgotten DB dumps or accidentally committed videos.

---

## Recipe 9 — Quickly find a file

**Scenario:** *"I know I have a config file with the SMTP credentials but
I forget where it lives."*

**Prompt:**
> *"On the server, find any file with 'smtp' in the name or content."*

**What happens:** `file_search` runs (excludes vendor/node_modules/.git
automatically). Returns matching paths + a snippet of the matching content.

---

## Recipe 10 — Review what you did last session

**Scenario:** You're picking up a project after a week away.

**Prompt:**
> *"What did I do in this project last session? Show me the deploy log and any saved knowledge."*

**What happens:**
1. `session_history` — pulls the last 10 session summaries
2. `deploy_log_recent` — shows the last 20 deploy/command entries
3. `knowledge_get` — loads project knowledge entries

Claude weaves these into a "you last touched this on Tuesday, you ran
migrations, here are the open questions" briefing.

---

## Multi-server / hub mode (Pro and Agency tiers)

If you've registered remote Server Agents in the admin panel
(Settings → Servers), you can target them by name from the chat:

**Prompt:**
> *"On the staging server (named 'stg'), show me the git status."*

**What happens:** `git_status` fires with `server="stg"`, the local hub
proxies the call to the remote Server Agent over MCP, and the result
streams back to you.

You can also set up workspaces for different projects on a single server:

**Prompt:**
> *"Use the 'api' workspace and tail the most recent log."*

(Workspaces are saved profiles in Settings → Projects, each with a
project root path and optional default branding.)

---

## Common gotchas

| Symptom | Cause | Fix |
|---|---|---|
| *"This connector has no tools available"* | OAuth flow registered but never completed | Click VOX in connectors → complete the browser login + Allow |
| *"Couldn't reload tools from the server"* | Schema bug in tools/list response | Update Server Agent to latest (this should be already fixed) |
| Tool says *"shell_exec is disabled"* | Shared host has `shell_exec` off | `host_capabilities` will list which tools are unavailable. Move to a VPS or contact host. |
| Tool says *"License required"* | Tier is unlicensed | Settings → License → activate via CodeCanyon, Gumroad, or manual key |
| Tool returns nothing for a workspace name | Workspace not registered | Settings → Projects → save a profile, OR use absolute paths in your prompt |
| Logs show `'C:\Program' is not recognized` (Windows + Claude Desktop) | Claude Desktop's `npx` quoting bug | Run `scoop install nodejs` to install Node at a no-spaces path, OR use Cursor / Claude Code (they speak HTTP natively) |

---

## Permission strategy — recommended starting set

The first time a tool is called, Claude Code (and most clients) ask for
approval. You can change per-tool defaults in the connector settings.
Recommended:

**Auto-approve (read-only, safe):**
`git_status`, `git_log`, `git_diff`, `file_read`, `file_browse`,
`file_search`, `ssl_check`, `dns_lookup`, `health_check`,
`host_capabilities`, `logs_list`, `log_tail`, `process_list`,
`disk_analyze`, `htaccess_audit`, `knowledge_get`, `project_profile`,
`deploy_log_recent`, `session_history`, `workspaces_list`, `envs_list`,
`backup_list`, `rollback_list`

**Needs approval (mutates):**
`bash_execute`, `file_write`, `db_query`, `service_control`,
`backup_create`, `rollback_restore`, `envs_switch`, `knowledge_save`

**Never (if you want zero risk of arbitrary execution):**
`bash_execute`, `service_control` — disable these and Claude will fall
back to using more specific tools (git_*, log_tail, etc.) for the same
workflows.

---

## What to ask first when you start a new project

Drop these prompts into a fresh conversation as a warm-up:

1. *"What tools does server-agent have on this host?"* → `host_capabilities`
2. *"What workspaces are registered?"* → `workspaces_list`
3. *"What do I know about this project?"* → `knowledge_get` + `project_profile`
4. *"What did I last do here?"* → `session_history`

After that, you've got the full context loaded and can drive normally.