Available Tools

PodWarden exposes 121 tools through MCP, organized by category. Tools are classified as read-only, mutating (create/update/deploy), or destructive (delete). The MCP Access Level setting (Settings → MCP) controls which tiers are exposed.

Renamed tools: The list_workload_definitions / get_workload_definition / etc. tools have been renamed to list_stacks / get_stack / etc. Similarly, list_workload_assignments / get_workload_assignment / etc. are now list_deployments / get_deployment / etc. The old names still work as backward-compatible aliases.

Infrastructure overview

Tool	Type	Description
`get_infrastructure_overview`	Read	High-level summary: cluster count, host count, GPU totals, workload status, recent deployments
`find_gpu_capacity`	Read	Find available GPU capacity across all hosts and clusters, grouped by GPU model
`check_cluster_capacity`	Read	Check available CPU and memory capacity across clusters, compare against deployed workloads
`troubleshoot_workload`	Read	Diagnose issues: fetches deployment, stack, cluster status, pod events, and logs

Clusters

Tool	Type	Description
`list_clusters`	Read	List all Kubernetes clusters with node counts, network types, and live status
`get_cluster`	Read	Detailed cluster info including nodes, managers, and live Kubernetes status
`get_cluster_extended`	Read	Extended live info: K8s version, namespaces, node details with CPU/memory/GPU, running pods
`get_cluster_storage_classes`	Read	List StorageClasses available in a cluster
`get_cluster_affected`	Read	Get resources that would be affected by deleting a cluster (hosts, deployments, endpoints)
`create_cluster`	Mutating	Create a new cluster — provide kubeconfig directly or fetch via SSH from a control-plane node
`update_cluster`	Mutating	Update cluster settings: name, kubeconfig, namespace, SSH fetch host, protection
`delete_cluster`	Destructive	Delete a cluster record from PodWarden (does NOT uninstall K8s from hosts)
`delete_cluster_node`	Destructive	Remove a stale node from a Kubernetes cluster (deletes the K8s node object)

Hosts

Tool	Type	Description
`list_hosts`	Read	List all managed hosts with hardware info, status, GPU details, cluster membership
`get_host`	Read	Full host details including hardware specs, GPU info, cluster assignment
`update_host`	Mutating	Update host metadata: display name, notes, network types
`probe_host`	Mutating	SSH into a host to gather hardware info (CPU, RAM, disk, GPU) and detect Kubernetes
`discover_hosts`	Mutating	Trigger Tailscale host discovery — fetches devices and upserts into PodWarden
`set_gateway_role`	Mutating	Enable or disable the gateway role on a host (ingress entry point)
`detect_host_public_ip`	Mutating	Detect the public IP of a host via SSH (for DNS validation)
`add_host`	Mutating	Add a host manually by IP or hostname (for non-Tailscale hosts)
`provision_host`	Mutating	Install K3s agent and join the host to a cluster (runs in background)
`wipe_host`	Mutating	Remove K3s from a host and reset to discovered state (runs in background)
`register_cluster_from_host`	Mutating	Register an existing K3s/K8s installation on a host as a PodWarden cluster
`provision_as_control_plane`	Mutating	Install K3s server on a host and create a new cluster (runs in background)
`detach_host_from_cluster`	Mutating	Remove a worker node from its cluster (K8s + PodWarden DB)
`delete_host`	Destructive	Delete a manually-added host from PodWarden

Stacks

Templates that define what to deploy (image, resources, GPU requirements).

Tool	Type	Description
`list_stacks`	Read	List all stacks with resource summaries
`get_stack`	Read	Full stack details including env schema, volume mounts, registry credentials
`create_stack`	Mutating	Create a new stack (container template)
`update_stack`	Mutating	Update an existing stack — only provided fields are changed
`delete_stack`	Destructive	Permanently delete a stack

Deployments

Bindings of stacks to clusters — the actual deployments.

Tool	Type	Description
`list_deployments`	Read	List deployments with status, cluster, stack, and deploy info
`get_deployment`	Read	Full deployment details including env values, resolved volumes, deployment log
`get_workload_logs`	Read	Get container logs and pod status from a deployed workload
`check_network_compatibility`	Read	Pre-flight check: verify workload network requirements match cluster capabilities
`create_deployment`	Mutating	Bind a stack to a cluster (starts in "pending" status)
`update_deployment`	Mutating	Update deployment config — changes take effect on next deploy
`deploy_workload`	Mutating	Deploy a deployment to its target Kubernetes cluster (runs in background)
`undeploy_workload`	Mutating	Remove a workload from Kubernetes — deletes Deployment and non-retained PVCs
`update_config_template`	Mutating	Update a single config template in a deployment without resending all config_values
`run_in_pod`	Mutating	Execute a command inside a running pod belonging to a managed deployment
`proxy_to_service`	Mutating	Send an HTTP request to a deployment's ClusterIP service via in-cluster proxy
`migrate_workload`	Mutating	Migrate a deployed workload to a different node (pre-flight PV affinity checks)
`delete_deployment`	Destructive	Delete a deployment record (does NOT undeploy — undeploy first)

Apps

Tool	Type	Description
`list_apps`	Read	List apps with their stacks, deployments, and current status
`get_app`	Read	Full app details including stack config, deployment status, and history
`rollback_deployment`	Mutating	Rollback to a previous deployment version — updates the K8s deployment image tag

Ingress rules

Tool	Type	Description
`list_ingress_rules`	Read	List all ingress rules with domain, backend, gateway, and status
`get_ingress_rule`	Read	Full ingress rule details including DNS check results and proxy status
`create_ingress_rule`	Mutating	Create a new ingress rule — supports managed (K8s) and manual (IP:port) backends
`update_ingress_rule`	Mutating	Update an existing ingress rule — only provided fields are changed
`check_ingress_dns`	Mutating	Check DNS resolution — resolves domain A record and compares to gateway IP
`check_ingress_http`	Mutating	HTTP health check — verifies the full chain: DNS → gateway → ingress → backend
`check_ingress_tls`	Mutating	Check TLS certificate validity: issuer, expiration date, days remaining
`apply_ingress_rule`	Mutating	Generate and deploy proxy config for a single ingress rule
`apply_all_ingress_rules`	Mutating	Regenerate and deploy the full proxy config for a gateway host
`delete_ingress_rule`	Destructive	Permanently delete an ingress rule and remove its proxy config

DDNS

Tool	Type	Description
`list_ddns_configs`	Read	List all DDNS configurations with provider, status, current IP, and last update
`get_ddns_config`	Read	Full DDNS config details (sensitive fields like API tokens are masked)
`get_ddns_status`	Read	Current public IP and status summary of all DDNS configurations
`create_ddns_config`	Mutating	Create a new DDNS config (Cloudflare, DuckDNS, Webhook, or Hub provider)
`update_ddns_config`	Mutating	Update a DDNS config — use "***" for token fields to preserve existing values
`test_ddns_config`	Mutating	Force a DNS record update to verify credentials and provider connectivity
`delete_ddns_config`	Destructive	Delete a DDNS config (DNS records are NOT removed — clean up at provider)

Hub catalog

Browse and import stack templates from PodWarden Hub.

Tool	Type	Description
`test_hub_connection`	Read	Test connectivity to the configured PodWarden Hub
`list_hub_categories`	Read	List template categories (e.g. "AI & Machine Learning", "Databases")
`list_hub_templates`	Read	Browse templates with search and category filtering
`get_hub_template`	Read	Full template details: image, resources, env schema, ports, volumes
`check_hub_updates`	Read	Check for updates on Hub-imported stacks
`import_hub_template`	Mutating	Import a Hub template as a local stack

Hub DDNS

Manage DDNS subdomains allocated through PodWarden Hub.

Tool	Type	Description
`list_hub_ddns_domains`	Read	List available DDNS domains from Hub (e.g. vxloc.com)
`list_hub_ddns_subdomains`	Read	List allocated subdomains with current IP addresses
`allocate_hub_ddns_subdomain`	Mutating	Allocate a new subdomain (e.g. "myapp.vxloc.com")
`update_hub_ddns_subdomain_ip`	Mutating	Update the IP address for an allocated subdomain
`delete_hub_ddns_subdomain`	Destructive	Release a Hub DDNS subdomain (stops resolving, cannot be undone)

Storage

Tool	Type	Description
`list_storage_connections`	Read	List all storage connections (NFS/S3 backends) with config and status
`get_storage_connection`	Read	Storage connection details including connectivity test results
`test_storage_connection`	Mutating	Test connectivity — NFS: TCP/RPC/export/mount+speed test; S3: endpoint/upload/download speed
`create_storage_connection`	Mutating	Create a new storage connection (NFS or S3)
`update_storage_connection`	Mutating	Update an existing storage connection — only provided fields are changed
`create_nfs_storage_class`	Mutating	Deploy NFS provisioner to a cluster and create a StorageClass from an NFS storage connection
`delete_storage_connection`	Destructive	Delete a storage connection (workloads using it will lose access)

Provisioning jobs

Tool	Type	Description
`list_provisioning_jobs`	Read	List provisioning jobs with status, host, playbook, and timing
`get_provisioning_job`	Read	Full job details including stdout and stderr output
`cancel_provisioning_job`	Mutating	Request cancellation of a running provisioning job

Users

Tool	Type	Description
`list_users`	Read	List system users with role, status, and last active time
`get_user`	Read	Full user details
`create_user`	Mutating	Create a new system user with email and role
`update_user`	Mutating	Update a user's name, email, role, or status
`set_user_password`	Mutating	Set or change a user's local password (8-72 characters)
`delete_user`	Destructive	Remove a system user

Secrets

Tool	Type	Description
`list_secrets`	Read	List all secret keys — values are NOT returned, only key names and metadata
`list_ssh_key_pairs`	Read	List SSH key pair names (each pair is `{name}_ssh_private` + `{name}_ssh_public`)
`get_secret`	Mutating	Get a decrypted secret value by key (handle with care)
`set_secret`	Mutating	Create or update a secret — value is encrypted at rest (AES-256-GCM)
`generate_ssh_key_pair`	Mutating	Generate a new SSH key pair and store both halves in secrets
`delete_secret`	Destructive	Delete a secret by key — cannot delete SSH keys in use by provisioned hosts

Settings

Tool	Type	Description
`get_settings`	Read	Get registry default settings (default registry URL and image tag)
`get_tailscale_settings`	Read	Get Tailscale configuration (tailnet, API key status, discovery tags)
`update_settings`	Mutating	Update registry default settings
`update_tailscale_settings`	Mutating	Update Tailscale configuration (tailnet, API key, discovery tags)

System configuration

Tool	Type	Description
`get_system_config`	Read	Get SMTP, OIDC, and Hub settings (env vars override DB values)
`update_system_config`	Mutating	Update system config — only pass sections to change (SMTP, OIDC, Hub)
`test_smtp`	Mutating	Send a test email using the configured SMTP settings
`test_oidc`	Mutating	Test OIDC discovery — validates issuer URL, fetches provider metadata

Role restrictions

Not all tools are available to all token roles. The token's role is enforced on the internal API calls each tool makes:

Action	viewer	operator	admin
Read tools (list, get, logs)	Yes	Yes	Yes
Mutating tools (create, update, deploy)	No	Yes	Yes
Destructive tools (delete, undeploy)	No	No	Yes
Secret values (get_secret)	No	No	Yes
System config (update)	No	No	Yes
User management (create, update, delete)	No	No	Yes

If a tool is called with insufficient permissions, the internal API returns 403 Forbidden, which the AI assistant sees as a tool error.