mcp-k8s-ephemeral-job

English | Русский

Public OSS MCP server (Go, MIT) that spawns an ephemeral Kubernetes Job/pod from a caller-chosen image, runs a command inside it, returns exit_code / stdout / artifacts, and deletes the pod. The server builds the pod manifest in code — the caller passes parameters only, never raw YAML.

It is the "operating room" counterpart to mcp-exec (the "scalpel"): where mcp-exec runs a single Python file in a locked-down, network-less sandbox in milliseconds, this one spins up a full pod with the toolchain/image you choose, controlled network (clone repos, pull deps), long tasks and file artifacts out. They complement each other.

Works over three transports — stdio / HTTP / SSE — with an identical tool set everywhere (official modelcontextprotocol/go-sdk).

Tools

run_job — run and wait

Input: { image (required), command (required), files?, env?, limits?, timeout_s?, workdir?, clone? } Output: { exit_code, stdout, stderr, duration_ms, status, artifacts, truncated }

• status is one of succeeded / failed / timeout / error. A non-zero exit_code or a timeout is a normal result, not a tool error. Only invalid input (empty image/command, image not in the allowlist, bad file path) is a tool-call error.
• stdout carries the container's combined stdout+stderr — Kubernetes merges the two streams in pod logs. stderr is reserved and always empty, so adding stream separation later stays backward-compatible.
• Artifacts (files from the working directory) come back inline (base64) under a size cap. Exceeding a cap never loses data silently: the matching truncated flag is set.
• The manifest is built deterministically by the server — no raw YAML from the caller.

submit_job / fetch_job — run in the background

submit_job takes the same arguments as run_job but returns a job_token immediately; fetch_job collects the result later. This is what lets an agent start a long job (a full test battery, a build) and keep working instead of idling inside one synchronous call for its whole wall-clock time.

• fetch_job returns status=running while the job is in flight; pass wait_s (≤120) to long-poll instead of hammering. It answers as soon as the job is done rather than sitting out the full wait.
• Results are retained for 60 minutes and can be fetched more than once.
• Arguments are validated at submit time, so a bad image fails the submit while the caller can still fix it.
• Handles live in memory (the server is single-replica by design): a restart drops pending tokens and the caller simply resubmits.

Cloning a repository

With clone: { repo_url, ref, subdir? } an init container checks the repo out into the working directory before the command runs. The caller never handles credentials: the server holds a secret with one token per git host, mounts it only on the cloner, and the token is masked in .git/config afterwards — the main container never sees it. The clone field is accepted only when the operator has configured MCP_K8S_CLONE_IMAGE + MCP_K8S_CLONE_SECRET.

Security model (invariants)

Per run: a fresh ephemeral pod, deleted afterwards (success / failure / timeout). The server's RBAC is namespace-scoped (Role/RoleBinding, never ClusterRole) — create/delete jobs,pods plus pods/log, pods/exec in one namespace. Spawned pods run with cap-drop=ALL, no-privilege-escalation, seccomp RuntimeDefault. The blast radius is that one namespace: LimitRange (per-pod default+max) + ResourceQuota (namespace ceiling) + wall-clock timeout (→ kill) + TTL/owner-reference GC + a concurrency cap. Images must pass a strict allowlist (MCP_K8S_ALLOWED_IMAGES; empty = nothing runs). Caller data (command / files / output / artifacts) is never persisted and never logged in full — only metadata.

run_job is the most powerful surface there is (it creates pods). When embedding it in an agent, gate it behind that agent's tool-policy (trusted roles only).

Network note: the pod's network is not disabled (it's needed to clone repos / pull deps). Egress is controlled by a namespace NetworkPolicy (allowlist) as a deployment concern, not a right baked into the code. The invariant is ephemerality + deletion, not the absence of network.

Resources: the server's MCP_K8S_DEFAULT_CPU/MEMORY are pod requests (the scheduler's reservation). Limits are set only when the caller passes limits; otherwise the ceiling comes from the namespace LimitRange. Passing limits.memory also raises the memory request to match, since memory is incompressible and the pod must land on a node that actually has it.

Run

Published in the MCP Registry as io.github.inhuman/mcp-k8s-ephemeral-job; the image is on Docker Hub as idconstruct/mcp-k8s-ephemeral-job.

docker run --rm -i \
  -v "$HOME/.kube:/kube:ro" \
  -e MCP_K8S_KUBECONFIG=/kube/config \
  -e MCP_K8S_NAMESPACE=ephemeral-dev \
  -e MCP_K8S_ALLOWED_IMAGES=busybox:1.36,python:3.12-slim \
  idconstruct/mcp-k8s-ephemeral-job:latest

From source, against a dev cluster, over stdio:

go build -o mcp-k8s-ephemeral-job ./cmd/mcp-k8s-ephemeral-job
export MCP_K8S_KUBECONFIG=$HOME/.kube/config
export MCP_K8S_NAMESPACE=ephemeral-dev
export MCP_K8S_ALLOWED_IMAGES=busybox:1.36,python:3.12-slim
./mcp-k8s-ephemeral-job

In production the server runs in-cluster as a Deployment with its own ServiceAccount + Role/RoleBinding on the ephemeral namespace + ResourceQuota/LimitRange (+ optional egress NetworkPolicy), usually on the http transport.

Example call (run_job)

{
  "image": "python:3.12-slim",
  "command": ["python", "gen.py"],
  "files": [{ "path": "gen.py", "content_b64": "<base64 of a script writing out.png>" }],
  "limits": { "cpu": "500m", "memory": "256Mi" },
  "timeout_s": 30
}

Returns exit_code, captured output, and out.png inline in artifacts. Afterwards the pod is gone (kubectl get jobs,pods -n $NS is empty).

Optional auth (HTTP/SSE)

Set MCP_K8S_AUTH_TOKEN to require every HTTP/SSE request to carry a matching X-MCP-AUTH header (constant-time compare; 401 otherwise). Empty token disables it. Not applicable to stdio.

Configuration