167 lines
6.9 KiB
Markdown
167 lines
6.9 KiB
Markdown
# MCP Tool Usage Guide — When and Why
|
|
|
|
**For Vesper (AI assistant) reference**
|
|
|
|
This guide explains when to use MCP tools vs other approaches, and how each tool category helps in practice.
|
|
|
|
---
|
|
|
|
## The Core Principle
|
|
|
|
Use the **most targeted tool available**. MCP tools are purpose-built for the homelab — they handle auth, error formatting, and homelab-specific context automatically. Bash + curl is a fallback when no MCP exists.
|
|
|
|
```
|
|
MCP tool available? → Use MCP
|
|
No MCP but known API? → Use bash + curl/httpx
|
|
Needs complex logic? → Use bash + python3
|
|
On a remote host? → Use ssh_exec or homelab_ssh_exec
|
|
```
|
|
|
|
---
|
|
|
|
## Decision Tree by Task
|
|
|
|
### "Check if a service is running"
|
|
→ `check_url` for HTTP services
|
|
→ `list_containers` + `get_container_logs` for Docker containers
|
|
→ `ssh_exec` + `systemctl status` for systemd services
|
|
|
|
### "Deploy a config change"
|
|
1. Edit the compose file in the repo (Write tool)
|
|
2. `git commit + push` (bash)
|
|
3. `redeploy_stack` to trigger GitOps pull
|
|
|
|
### "Something broke — diagnose it"
|
|
→ `get_container_logs` first (fastest)
|
|
→ `check_portainer` for overall health
|
|
→ `prometheus_query` for metrics
|
|
→ `ssh_exec` for deep investigation
|
|
|
|
### "Add a new service"
|
|
1. Write compose file (Write tool)
|
|
2. `cloudflare_create_dns_record` for public DNS
|
|
3. `adguard_add_rewrite` if it needs a specific LAN override
|
|
4. `npm_list_proxy_hosts` + bash NPM API call for reverse proxy
|
|
5. `kuma_add_monitor` + `kuma_restart` for uptime monitoring
|
|
6. `authentik_list_applications` to check if SSO needed
|
|
|
|
### "Add a new Tailscale node"
|
|
1. `headscale_create_preauth_key` to generate auth key
|
|
2. Run `tailscale up --login-server=... --authkey=...` on the new host (ssh_exec)
|
|
3. `headscale_list_nodes` to confirm it registered
|
|
4. `adguard_add_rewrite` for `hostname.tail.vish.gg → <tailscale_ip>`
|
|
5. `kuma_add_monitor` for monitoring
|
|
|
|
### "Fix a DNS issue"
|
|
1. `adguard_list_rewrites` — check current overrides
|
|
2. Check if the wildcard `*.vish.gg → 100.85.21.51` is causing interference
|
|
3. `adguard_add_rewrite` for specific override before wildcard
|
|
4. `cloudflare_list_dns_records` to verify public DNS
|
|
|
|
### "Fix an Authentik SSO redirect loop"
|
|
1. `authentik_list_providers` to find the provider PK
|
|
2. `authentik_set_provider_cookie_domain` → set `vish.gg`
|
|
3. Check NPM advanced config has `X-Original-URL` header
|
|
|
|
### "Fix a cert issue"
|
|
1. `npm_list_certs` — identify cert IDs and expiry
|
|
2. `npm_get_proxy_host` — check which cert a host is using
|
|
3. `npm_update_cert` — swap to correct cert
|
|
4. **Never reuse an existing npm-N ID** when adding new certs
|
|
|
|
---
|
|
|
|
## Tool Category Quick Reference
|
|
|
|
### When `check_portainer` is useful
|
|
- Session start: quick health check before doing anything
|
|
- After a redeploy: confirm stacks came up
|
|
- Investigating "something seems slow"
|
|
|
|
### When `list_containers` / `get_container_logs` are useful
|
|
- A service is showing errors in the browser
|
|
- A stack was redeployed and isn't responding
|
|
- Checking if a container is actually running (not just the stack)
|
|
|
|
### When `adguard_list_rewrites` is essential
|
|
Any time a service is unreachable from inside the LAN/Tailscale network:
|
|
- `*.vish.gg → 100.85.21.51` wildcard can intercept services
|
|
- Portainer, Authentik token exchange, GitOps polling all need correct DNS
|
|
- Always check AdGuard before assuming network/firewall issues
|
|
|
|
### When `npm_*` tools save time
|
|
- Diagnosing SSL cert mismatches (cert ID → domain mapping)
|
|
- Checking if a proxy host is enabled and what it forwards to
|
|
- Swapping certs after LE renewal
|
|
|
|
### When `headscale_*` tools are needed
|
|
- Onboarding a new machine to the tailnet
|
|
- Diagnosing connectivity issues (is the node online?)
|
|
- Rotating auth keys for automated nodes
|
|
|
|
### When `authentik_*` tools are needed
|
|
- Adding SSO to a new service (check existing providers, create new)
|
|
- Fixing redirect loops (cookie_domain)
|
|
- Updating dashboard tile URLs after service migrations
|
|
|
|
### When `cloudflare_*` tools are needed
|
|
- New public-facing service needs a domain
|
|
- Migrating a service to a different host IP
|
|
- Checking if proxied vs unproxied is the issue
|
|
|
|
### When `kuma_*` tools are needed
|
|
- New service deployed → add monitor so we know if it goes down
|
|
- Service moved to different URL → update existing monitor
|
|
- Organising monitors into host groups for clarity
|
|
|
|
### When `prometheus_query` helps
|
|
- Checking resource usage before/after a change
|
|
- Diagnosing "host seems slow" (CPU, memory, disk)
|
|
- Confirming a service is being scraped correctly
|
|
|
|
### When `ssh_exec` is the right choice
|
|
- The task requires commands not exposed by any MCP tool
|
|
- Editing config files directly on a host
|
|
- Running host-specific tools (sqlite3, docker compose, certbot)
|
|
- Anything that needs interactive investigation
|
|
|
|
---
|
|
|
|
## MCP vs Bash — Specific Examples
|
|
|
|
| Task | Use MCP | Use Bash |
|
|
|------|---------|----------|
|
|
| List all Headscale nodes | `headscale_list_nodes` | Only if MCP fails |
|
|
| Get container logs | `get_container_logs` | Only for very long tails |
|
|
| Add DNS rewrite | `adguard_add_rewrite` | Never — MCP handles auth |
|
|
| Check cert on a proxy host | `npm_get_proxy_host` | Only if debugging nginx conf |
|
|
| Run SQL on Kuma DB | `kuma_add_monitor` / `kuma_set_parent` | Only for complex queries |
|
|
| Redeploy a stack | `redeploy_stack` | Direct Portainer API if MCP times out |
|
|
| SSH to a host | `ssh_exec` | `bash + ssh` for interactive sessions |
|
|
| Edit a compose file | Write tool + git | Never edit directly on host |
|
|
| Check SABnzbd queue | `sabnzbd_queue` | Only if troubleshooting API |
|
|
| List all DNS records | `cloudflare_list_dns_records` | Only for bulk operations |
|
|
|
|
---
|
|
|
|
## Homelab-Specific Gotchas MCP Tools Handle
|
|
|
|
### AdGuard wildcard DNS
|
|
The `*.vish.gg → 100.85.21.51` wildcard means many `*.vish.gg` domains resolve to matrix-ubuntu's Tailscale IP internally. `adguard_list_rewrites` quickly shows which services have specific overrides and which rely on the wildcard. Before blaming a network issue, always check this.
|
|
|
|
### NPM cert IDs
|
|
Each cert in NPM has a numeric ID (npm-1 through npm-12+). `npm_list_certs` shows the mapping. Overwriting an existing npm-N with a different cert breaks every proxy host using that ID — this happened once and took down all `*.vish.gg` services. `npm_list_certs` prevents this.
|
|
|
|
### Portainer endpoint IDs
|
|
Portainer has 5 endpoints with numeric IDs. The MCP tools accept names (`atlantis`, `calypso`, etc.) and resolve them internally — no need to remember IDs.
|
|
|
|
### Kuma requires restart
|
|
Every DB change to Uptime Kuma requires a container restart — Kuma caches config in memory. `kuma_restart` is always the last step after `kuma_add_monitor` or `kuma_set_parent`.
|
|
|
|
### Authentik token exchange needs correct DNS
|
|
When Portainer (on Atlantis) tries to exchange an OAuth code for a token, it calls `sso.vish.gg`. If AdGuard resolves that to the wrong IP, the exchange times out silently. Always verify DNS before debugging OAuth flows.
|
|
|
|
---
|
|
|
|
**Last updated:** 2026-03-21
|