Available Tools
Complete reference of MCP tools available in PodWarden
PodWarden offers 184 tools across 27 categories. A connected model is announced only the facade's own tools — find_tools, describe_tools, list_tool_categories, load_skill, and the execute_read / execute_mutate / execute_destroy doors — and discovers and calls everything else through them, so the full catalog never bloats the model's context. Tools are classified as read-only, mutating (create/update/deploy), or destructive (delete). The instance-wide tier switch (Settings → MCP) controls which of those tiers are exposed, and is the only setting that restricts what a connected model may call — a token's role does not. See What gates a tool call.
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) |
System Apps
Read-only tools for inspecting platform-level add-ons (operators) installed on a cluster, such as Longhorn or the backup operator.
| Tool | Type | Description |
|---|---|---|
list_system_apps | Read | List all system apps registered on a cluster with namespace, status, version, token state, and capabilities |
get_system_app | Read | Full details for a single system app (e.g. longhorn, backup-operator) including live status |
See the System Apps guide for installation and detection details.
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 |
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 |
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. podwarden.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.podwarden.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) |
update_settings | Mutating | Update registry default settings |
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 |
What gates a tool call
There is no per-token permission model. Earlier versions of this page described a viewer / operator / admin matrix in which mutating and destructive tools returned 403 Forbidden to a lower-privileged token. No such gate exists. PodWarden Core's authorization model is flat: every authenticated caller has the same access, secret values included. The role stored on an MCP token (admin or readonly) is displayed in the UI but is read by no authorization check.
Selecting a role does not limit a token. If you need to limit what an AI assistant can do, the control is the instance-wide tier switch below — or the decision not to mint the token at all.
Three things actually decide whether a tool call succeeds. None of them is the token's role.
1. Authentication
The request must carry a valid Bearer pwm_… token that is still active and unexpired. Anything else is rejected before tool gating runs. An MCP path whose identity cannot be resolved fails closed and exposes nothing.
2. The instance-wide tier switch
Set in Settings → MCP. This is the only gate that works at tool granularity:
| Tier | Covers | Default |
|---|---|---|
read | Read tools — list_*, get_*, logs, capacity and health checks | Enabled |
mutate | Create / update / deploy tools — and get_secret, deliberately classified as mutating so a read-only instance cannot disclose secret values | Disabled |
destroy | Delete / release tools | Disabled |
It is an operator switch for the whole deployment, not a per-principal permission: it applies identically to every caller, and a token whose stored role reads admin is capped by it exactly like any other. If the setting cannot be read, it fails safe to read-only.
Because the tier filter runs before the facade is announced, a Core with mutate and destroy off does not announce the execute_mutate and execute_destroy doors at all — the connected model is offered only the read door.
A tool outside an enabled tier returns an MCP error frame rather than an HTTP status, carrying a stable reason code:
| Reason | Meaning |
|---|---|
tier_disabled | The tool exists, but its tier is switched off for this instance |
unknown_tool | No tool by that name is registered |
3. Credential-class rules
These key on how you authenticated, not on what role you hold — so they are not a role system returning by another name, and they apply to every MCP token equally. An MCP token is a machine credential, and machine credentials are refused (403 Forbidden) on the surfaces that administer other credentials:
| Surface | Effect on an MCP token |
|---|---|
create_user, update_user, set_user_password, delete_user | Refused. Reading users (list_users, get_user) is unaffected |
| Creating or modifying MCP tokens | Refused — a token cannot mint itself a more capable successor |
The terminal and runtime sections of update_system_config | Refused. The other sections are unaffected |
| Environment inventory | Refused |
| Approving or extending a node-access grant | Refused — approval requires an interactive human |
One genuine per-token setting exists: node_ssh_access, disabled by default, which grants a root shell on managed nodes. An operator turns it on for an individual token, and it is re-validated live against the database on every use. See Node SSH access.
Scope an MCP token by whether you mint it, not by how you configure it. Within the enabled tiers, any valid token can read every secret the instance holds and change everything it manages. This posture is only appropriate while everyone who can authenticate to the instance is trusted with full administrative access to it; it is not a model for a deployment with users of differing trust.