Skip to main content
Version: Next 🚧

Installing the Epinio MCP Server

The Epinio MCP server exposes Epinio as tools for AI agents over the Model Context Protocol. It runs on your cluster and talks to the Epinio API on the agent's behalf. For the full tool list and the optional elevated tier, see the MCP server reference.

Beta

The MCP server is in beta. Tool names and options may still change, and it is not yet recommended for production use.

Prerequisites​

  • A Kubernetes cluster with Epinio 1.14.1 or later installed. The server relies on the builder-image, catalog-service, and app-chart CRUD API and the source-retrieval endpoint added in 1.14.1, so it will not work against earlier releases.
  • kubectl and the epinio CLI pointed at your cluster.
  • make and a Go toolchain, plus a clone of epinio/mcp.

Choose an install path​

There are two ways to install the server. Most users want the first.

PathUse when
make setup (managed)You want Epinio to own the lifecycle (push, logs, restart, scale), just like any other app.
kubectl apply (adopted)You want the server managed outside Epinio's REST path, and prefer to finish setup through conversation with the agent.

Clone epinio/mcp, set your cluster details in epinio.yml, and run:

make setup

This targets the mcp namespace (creating it if needed), pushes the server, and smoke-tests /healthz and /readyz. Override the namespace with make setup NAMESPACE=<name>, and run make help to see every target.

epinio.yml carries the connection details. Fill in the environment section with your cluster's API URL and credentials (default admin / password):

environment:
  EPINIO_API_URL: "https://epinio.your-cluster.example.com"
  EPINIO_USERNAME: "admin"
  EPINIO_PASSWORD: "your-password"

For OIDC clusters, leave the username and password empty and set EPINIO_TOKEN, EPINIO_REFRESH_TOKEN, and EPINIO_TOKEN_ENDPOINT instead.

The push runs the full build cycle (upload source, stage, deploy, wait for ready) and assigns a route, for example https://epinio-mcp.192.168.X.X.sslip.io. The MCP endpoint is that route's root — point your agent at the URL as-is (no /mcp suffix).

Elevated tier (optional)​

The core install wires only to the Epinio API. To turn on the opt-in elevated tier — workload adoption, which reaches directly into Kubernetes — edit epinio-elevated.yml and run:

make elevated-setup

This registers the standard-elevated app chart (a one-time, cluster-admin step) and pushes the server with EPINIO_MCP_ELEVATED set. Switching a running server between the core and elevated installs recreates it (the app chart can't change in place).

Install with kubectl apply​

This path stands the server up as a plain Kubernetes workload with the adoption RBAC. The install manifest is self-contained: it creates the namespace, the server's ServiceAccount and RBAC, the Deployment and Service, and an Epinio App record so epinio app list/show/logs keep working.

Deploy the server (edit the image tag, credentials, and Ingress host first):

kubectl apply -f install/epinio-mcp.yaml
kubectl -n epinio rollout status deployment/epinio-mcp

Once it is running, ask the agent to finish its own setup:

Run enable_capability for self_adoption.

To upgrade, edit the image tag and re-apply install/epinio-mcp.yaml; to uninstall, run kubectl delete -f install/epinio-mcp.yaml.

Verify the server is up​

The server exposes two plain-HTTP probes:

# Liveness
curl https://epinio-mcp.<your-route>/healthz

# Readiness (confirms the server can reach Epinio)
curl https://epinio-mcp.<your-route>/readyz

A healthy /readyz response reports the Epinio version it reached:

{"epinio":{"kube_version":"...","platform":"...","version":"..."},"status":"ok","version":"..."}

See also​