MCP tools

This is the product’s contract: the complete set of mcp__kubrain__* tools an agent drives. Every tool also exists as a kubrain CLI verb — same engine, identical results. Each tool carries its own current parameter docs; read the tool’s own description before first use — the tables below are the map, not a substitute for it.

Conventions used below:

Mutates — no tools are always safe to call; yes tools change infra or spend. Create/set tools are idempotent (safe to repeat to “ensure” state).
Cost-aware tools have a dry path (dry_run, or a dedicated estimate/plan).
Public tools need no tenant token (the pre-signup quote surface); everything else authorizes against your tenant, funds, and quota on every call.

Networking (VPCs)

A VPC is a regional, tenant-isolated network. Clusters in the same VPC talk to each other region-wide; different VPCs are isolated.

Tool	Mutates	What it does
`create_vpc(name, region?)`	yes	Ensure a VPC exists (idempotent).
`get_network(name)`	no	Show one VPC (CIDR, gateway, region).
`list_networks()`	no	All your VPCs.
`delete_vpc(name)`	yes	Tear down the VPC’s network.

Clusters

Tool	Mutates	What it does
`list_versions()`	no	Selectable Kubernetes versions (+ the Talos image version).
`get_regions()`	no	Regions/zones that actually exist, with coarse free capacity.
`create_cluster(name, vpc?, tier?, ram?, nodes?, k8s?, dry_run?)`	yes	Plan (dry-run, the default) or provision a cluster. Dry-run returns IPs, public endpoint, and cost, applying nothing.
`list_clusters()`	no	Your clusters with state, tier, VPC, node count, public hostname.
`get_cluster(name)`	no	One cluster’s status (state, shape, network, endpoint, recent Events).
`get_kubeconfig(name, output_file)`	no	Write a kubeconfig (server set to the public endpoint) to a file.
`scale_cluster(name, nodes)`	yes	Add/remove worker nodes (`normal`/`ha`). Async.
`resize_cluster(name, ram)`	yes	Change per-node RAM; rolls the worker pool. Async.
`upgrade_cluster(name, k8s)`	yes	Upgrade Kubernetes — control plane first, then workers. Async.
`reapply_cluster(name)`	yes	Re-render the manifest unchanged to pick up platform features (may roll the CP once).
`delete_cluster(name)`	yes	Tear down (cascades to VMs), free the network block. Confirm first.

Tiers. dev (1 schedulable control plane, 0+ workers — prototypes) · normal (1 dedicated control plane, 1+ workers — small non-critical apps) · ha (3 control planes across ≥3 zones, 1+ workers — production). ram is GiB per node (the billed dimension); region is inherited from the VPC.

Add-ons

Tool	Mutates	What it does
`list_addons()` (public)	no	The curated catalogue with pinned versions + cost impact.
`install_addon(cluster, addon, issuer_email?, dry_run?)`	yes	Install a pinned add-on (idempotent). Dry-run returns `monthly_delta_eur`.
`uninstall_addon(cluster, addon)`	yes	Remove it; uninstalling ingress-nginx releases its LB IP (charge stops).

Catalogue: ingress-nginx (HTTP(S) ingress behind a dedicated LB IP, +€3.50/mo) · cert-manager (free Let’s Encrypt TLS; pass issuer_email) · metrics-server (free; kubectl top, HPA) · redis (free in-cluster cache; publishes a redis-auth Secret you reference with addon: redis).

Cost & quota

Tool	Mutates	What it does
`pricing()` (public)	no	The rate card: RAM €/GiB-h, volume €/GiB-mo (+ free allowance), LB IP €/mo, tier shapes.
`estimate(tier, ram, nodes, volume_gib?, lb_ips?)` (public)	no	Exact €/hour and €/month for a shape, with a per-dimension breakdown. Creates nothing.
`get_quota()`	no	Limits and usage per dimension + €/month burn and spend cap.
`usage(month?)`	no	Month-to-date consumption: GiB-hours + € per dimension and per resource, including deleted ones. `month=YYYY-MM` for a past month.

Deployments

An app is a deployment — a named handle on a cluster you ship releases to. Its name is also its namespace, kbn-<name>.

Tool	Mutates	What it does
`create_deployment(name, cluster, repo?, branch?)`	yes	Create the handle (idempotent). `repo`/`branch` binds Git for auto-builds.
`list_deployments()`	no	Inventory + state.
`get_deployment(name)`	no	Release ledger, current pointer, rollout status, secret names (never values).
`deploy(name, dir?/image?)`	yes	Ship a release: build local source in the cloud → push → roll out, or roll out a prebuilt `image`.
`rollback_deployment(name, release?)`	yes	Re-point to a prior release and re-apply its exact manifests (no rebuild).
`promote_deployment(src, to, release?)`	yes	Ship one deployment’s tested image on another — no rebuild (e.g. staging → prod).
`set_trigger(name, spec)`	yes	Auto-build policy for a Git deployment: `manual`, `commit:<glob>`, `tag:<glob>`, `schedule:<cron>`.
`get_deploy_key(name)`	no	The read-only ed25519 public deploy key to add to your Git repo.
`delete_deployment(name)`	yes	Tear down the app’s namespace. Confirm first.

Build helpers (client-local)

These run on your machine — stack detection and manifest authoring against the same render engine the cloud uses. They upload nothing.

Tool	Mutates	What it does
`detect(path)`	no	Report the detected stack (language, ports, existing files).
`scaffold(path)`	no*	Write a starter `kubrain.yaml` (+ Dockerfile); never clobbers.
`validate(path)`	no	Lint `kubrain.yaml` (+ templates) with the cloud’s exact checks.

Secrets

Tool	Mutates	What it does
`set_secret(name, key, value_file)`	yes	Write an app env secret into the cluster’s Secret; only the key name is recorded centrally, never the value.
`unset_secret(name, key)`	yes	Remove a secret key.

Registry

Tool	Mutates	What it does
`get_registry()`	no	Push coordinates (host + your `<tenant>/` namespace + login). Clusters pull with no `imagePullSecrets`.

DNS

Tool	Mutates	What it does
`create_zone(domain)`	yes	Host a domain (free, idempotent); returns the NS set to delegate at your registrar.
`list_zones()` / `delete_zone(domain)`	no / yes	List hosted zones / stop hosting (removes all records).
`set_record(zone, name, type, value, ttl?)`	yes	Upsert an RRset (A, AAAA, CNAME, TXT, MX, SRV, CAA). Live on both nameservers immediately.
`list_records(zone)` / `delete_record(...)`	no / yes	List / delete a record set.

Object storage (buckets)

Tool	Mutates	What it does
`create_bucket(name, public?)`	yes	An S3-compatible bucket; `public` (fixed at creation) = anonymous read.
`list_buckets()` / `delete_bucket(name)`	no / yes	Inventory with live object count + size / delete (empty buckets only).
`get_bucket_credentials(output_file)`	no	Write the tenant’s S3 key pair to a file — one pair opens all your buckets.

Observability

Tool	Mutates	What it does
`get_metrics(name, component?, window?, by?)`	no	Golden signals — request rate, 5xx error rate (0..1), p95 latency (ms) — with zero app instrumentation.
`set_alert(deployment, …, notify)`	yes	Threshold on a signal (metric / pod health / ingress uptime+TLS); fires a webhook or email on breach and recovery. Idempotent per rule.
`list_alerts(deployment)`	no	Each rule’s live state (`ok`/`pending`/`firing`) and last sampled value.

Blueprints (declarative fleet)

Manage the whole tenant as one versioned, diffable document.

Tool	Mutates	What it does
`export_blueprint(refs?)`	no	Snapshot current resources as an intent spec (status fields left out).
`estimate_blueprint(file)`	no	Price the whole document.
`plan_blueprint(file)`	no	Diff spec vs. live — create / update / delete / no-op per resource.
`apply_blueprint(file, prune?)`	yes	Converge live state to the document. `prune` also deletes undeclared resources (confirm first).