Kubernetes Ephemeral Job

Official

by inhuman · Go

Runs a command in a throwaway Kubernetes pod and returns exit code, output and artifacts.

io.github.inhuman/mcp-k8s-ephemeral-job MCP Server

The io.github.inhuman/mcp-k8s-ephemeral-job Model Context Protocol (MCP) server runs a command in a throwaway Kubernetes pod and returns the command’s exit code, output, and artifacts. It is designed to execute ephemeral workloads in Kubernetes and surface results to the calling client.

🛠️ Key Features

Executes commands inside a throwaway Kubernetes pod
Returns exit code and command output
Returns produced artifacts

🚀 Use Cases

Running short-lived Kubernetes-executed jobs
Capturing command results (exit code, output) for downstream handling
Collecting artifacts generated during ephemeral execution

⚡ Developer Benefits

Predictable per-run isolation via ephemeral pods
Structured retrieval of execution outcomes (exit code/output/artifacts)

README.md10 KBView on GitHub

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.

bash

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:

bash

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`)

json

{
  "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

Env var	Purpose	Default
`MCP_K8S_TRANSPORT`	`stdio` \| `http` \| `sse`	`stdio`
`MCP_K8S_ADDR`	listen address for http/sse	`:8080`
`MCP_K8S_NAMESPACE`	namespace where ephemeral pods are spawned	`mcp-ephemeral`
`MCP_K8S_DEFAULT_TIMEOUT_S`	default wall-clock timeout (s)	`60`
`MCP_K8S_MAX_TIMEOUT_S`	timeout ceiling (s)	`600`
`MCP_K8S_MAX_OUTPUT_BYTES`	combined stdout+stderr cap	`1048576`
`MCP_K8S_MAX_ARTIFACT_BYTES`	total artifacts size cap	`10485760`
`MCP_K8S_DEFAULT_CPU`	pod CPU request (scheduling reservation; limits come from the caller's `limits` or the namespace LimitRange)	`1`
`MCP_K8S_DEFAULT_MEMORY`	pod memory request (see above)	`512Mi`
`MCP_K8S_MAX_CONCURRENT`	max concurrent ephemeral pods (over → queue/error)	`10`
`MCP_K8S_ALLOWED_IMAGES`	strict image allowlist (CSV); empty = deny everything	``
`MCP_K8S_SIDECAR_IMAGE`	helper sidecar image for artifact collection (pinned)	`busybox:1.36`
`MCP_K8S_CLONE_IMAGE`	image with git for the clone init container; empty = `clone` unavailable	``
`MCP_K8S_CLONE_SECRET`	secret holding one token per git host (key = host); mounted only on the cloner	``
`MCP_K8S_CACHE_PVC`	existing PVC mounted into every job pod as a shared cache; empty = no cache	``
`MCP_K8S_CACHE_MOUNT_PATH`	where the cache PVC is mounted, e.g. `/go/pkg/mod`	``
`MCP_K8S_JOB_EXTRA_ENV`	JSON object `{"KEY":"value"}` added to every job pod; caller keys win	``
`MCP_K8S_KUBECONFIG`	path to kubeconfig; empty = in-cluster	``
`MCP_K8S_AUTH_TOKEN`	if set, http/sse require `X-MCP-AUTH` header (constant-time); empty = off	``

Both cache variables must be set together for the cache to mount. The PVC itself is provisioned out-of-band (helm/manifest); the server only references it by name and fails fast at startup if it is missing.

Not implemented

PVC / object-storage delivery for artifacts too large to inline, multi-cluster support, and proxying other MCP servers into the pod.

License

MIT.

Install

Configuration

Environment variables

MCP_K8S_ALLOWED_IMAGESrequired

Strict image allowlist (CSV). Empty means every call is rejected, so this must be set.

MCP_K8S_KUBECONFIGdefault /kube/config

Path to the kubeconfig inside the container. Empty = use in-cluster credentials.

MCP_K8S_NAMESPACEdefault mcp-ephemeral

Namespace the ephemeral pods are created in. Needs a Role/RoleBinding for jobs and pods.

MCP_K8S_TRANSPORTdefault stdio

MCP transport: stdio | http | sse. Must be 'stdio' for direct docker/stdio use.

MCP_K8S_DEFAULT_TIMEOUT_Sdefault 60

Default wall-clock timeout per job, seconds.

MCP_K8S_MAX_TIMEOUT_Sdefault 600

Maximum wall-clock timeout a caller may request, seconds.

MCP_K8S_MAX_OUTPUT_BYTESdefault 1048576

Cap on combined stdout/stderr before truncation.

MCP_K8S_MAX_ARTIFACT_BYTESdefault 10485760

Cap on the total size of returned artifacts.

MCP_K8S_MAX_CONCURRENTdefault 10

Maximum ephemeral pods running at the same time.

MCP_K8S_DEFAULT_CPUdefault 1

Pod CPU request; limits come from the caller or the namespace LimitRange.

MCP_K8S_DEFAULT_MEMORYdefault 512Mi

Pod memory request; limits come from the caller or the namespace LimitRange.

MCP_K8S_SIDECAR_IMAGEdefault busybox:1.36

Helper image used to inject input files and collect artifacts.

MCP_K8S_CLONE_IMAGE

Image carrying git for the clone init container. Empty disables the clone field.

MCP_K8S_CLONE_SECRETsecret

Secret with git tokens, mounted only on the cloner. Empty disables the clone field.

MCP_K8S_CACHE_PVC

Existing PVC mounted into every job pod as a shared cache. Empty = no cache.

MCP_K8S_CACHE_MOUNT_PATH

Where the cache PVC is mounted, e.g. /go/pkg/mod. Empty = no cache.

MCP_K8S_JOB_EXTRA_ENV

JSON object of env vars added to every job pod; caller keys win on collision.

MCP_K8S_AUTH_TOKENsecret

Optional X-MCP-AUTH token required on every request (http/sse transports only).

Arguments

--volumedefault {kubeconfig_dir}:/kube:ro

--read-only

--cap-dropdefault ALL

--security-optdefault no-new-privileges

--memorydefault 256m

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-k8s-ephemeral-job": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/idconstruct/mcp-k8s-ephemeral-job:v0.7.1"
      ],
      "env": {
        "MCP_K8S_ALLOWED_IMAGES": "<YOUR_MCP_K8S_ALLOWED_IMAGES>",
        "MCP_K8S_KUBECONFIG": "/kube/config",
        "MCP_K8S_NAMESPACE": "mcp-ephemeral",
        "MCP_K8S_TRANSPORT": "stdio",
        "MCP_K8S_DEFAULT_TIMEOUT_S": "60",
        "MCP_K8S_MAX_TIMEOUT_S": "600",
        "MCP_K8S_MAX_OUTPUT_BYTES": "1048576",
        "MCP_K8S_MAX_ARTIFACT_BYTES": "10485760",
        "MCP_K8S_MAX_CONCURRENT": "10",
        "MCP_K8S_DEFAULT_CPU": "1",
        "MCP_K8S_DEFAULT_MEMORY": "512Mi",
        "MCP_K8S_SIDECAR_IMAGE": "busybox:1.36",
        "MCP_K8S_CLONE_IMAGE": "<YOUR_MCP_K8S_CLONE_IMAGE>",
        "MCP_K8S_CLONE_SECRET": "<YOUR_MCP_K8S_CLONE_SECRET>",
        "MCP_K8S_CACHE_PVC": "<YOUR_MCP_K8S_CACHE_PVC>",
        "MCP_K8S_CACHE_MOUNT_PATH": "<YOUR_MCP_K8S_CACHE_MOUNT_PATH>",
        "MCP_K8S_JOB_EXTRA_ENV": "<YOUR_MCP_K8S_JOB_EXTRA_ENV>",
        "MCP_K8S_AUTH_TOKEN": "<YOUR_MCP_K8S_AUTH_TOKEN>"
      }
    }
  }
}

io.github.inhuman/mcp-k8s-ephemeral-job MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

mcp-k8s-ephemeral-job

Tools

run_job — run and wait

submit_job / fetch_job — run in the background

Cloning a repository

Security model (invariants)

Run

Example call (run_job)

Optional auth (HTTP/SSE)

Configuration

Not implemented

License

Install

Configuration

`run_job` — run and wait

`submit_job` / `fetch_job` — run in the background

Example call (`run_job`)