homelab-optimized/docs/admin/mcp-usage-guide.md

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