Kubernetes Provider¶

The K8s provider automatically manages kubectl port-forward connections to your Unblu deployment. This is the recommended configuration for internal/development deployments.

Prerequisites¶

• kubectl installed and in PATH
• Authenticated to your K8s cluster (kubectl auth login or valid kubeconfig)
• Permissions to access services in the target namespace

The provider will check authentication before starting port-forward and provide helpful error messages if something is misconfigured.

Configuration¶

The provider loads environments from the first of these locations that exists:

• ~/.unblu-mcp/k8s_environments.yaml for normal uvx or uv tool install usage
• config/k8s_environments.yaml when running from a source checkout
• --k8s-config /path/to/k8s_environments.yaml to override both

Quick bootstrap:

mkdir -p ~/.unblu-mcp
uvx unblu-mcp --print-k8s-config-template > ~/.unblu-mcp/k8s_environments.yaml

The --environment value must match one of the keys under environments in that YAML file.

Example:

environments:
  dev:
    local_port: 8084
    namespace: unblu-dev
    service: haproxy
    service_port: 8080
    api_path: /app/rest/v4

  staging:
    local_port: 8085
    namespace: unblu-staging
    service: haproxy
    service_port: 8080
    api_path: /app/rest/v4

  prod:
    local_port: 8086
    namespace: unblu-prod
    service: haproxy
    service_port: 8080
    api_path: /app/rest/v4

Configuration Options¶

Usage¶

Command Line¶

# Use the dev environment from ~/.unblu-mcp/k8s_environments.yaml
unblu-mcp --provider k8s --environment dev

# Use a custom config file
unblu-mcp --provider k8s --environment my-env --k8s-config /path/to/config.yaml

MCP Client Config¶

{
  "mcpServers": {
    "unblu": {
      "command": "uvx",
      "args": ["unblu-mcp", "--provider", "k8s", "--environment", "dev"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

The env.PATH block is only needed if your MCP client does not already inherit a PATH that includes both uvx and kubectl.

Programmatic¶

from unblu_mcp import create_server, K8sConnectionProvider

# Connect to a K8s environment (starts kubectl port-forward automatically)
provider = K8sConnectionProvider(environment="dev")
server = create_server(provider=provider)

With custom environments:

from unblu_mcp import K8sConnectionProvider, K8sEnvironmentConfig

environments = {
    "custom": K8sEnvironmentConfig(
        name="custom",
        local_port=9000,
        namespace="my-namespace",
        service="my-service",
    )
}

provider = K8sConnectionProvider(
    environment="custom",
    environments=environments,
)

How It Works¶

1. On startup: The provider checks if the configured local port is already in use
2. If port is free: Starts a new kubectl port-forward process
3. If port is in use: Reuses the existing connection (from another MCP instance or manual port-forward)
4. Before each API call: Checks if the connection is still alive, restarts if needed
5. On shutdown: Terminates the port-forward process (only if this instance started it)

Auto-Restart¶

If the port-forward dies while the server is running, it will automatically restart on the next API call. This handles:

• Network interruptions
• Kubernetes pod restarts
• kubectl process crashes

Multiple Instances¶

Multiple MCP server instances can safely share the same port-forward:

• First instance starts the port-forward
• Subsequent instances detect the port is in use and reuse it
• When the owning instance shuts down, others continue working until they need to restart

Troubleshooting¶

kubectl not found¶

ConfigurationError: kubectl not found in PATH

Solution: Ensure kubectl is installed and add its directory to the PATH in your MCP client config:

{
  "env": {
    "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
  }
}

Authentication failure¶

ConfigurationError: kubectl is not authenticated or lacks permissions

Solution: Authenticate to your cluster:

kubectl auth login  # or your cluster's auth method
kubectl get pods -n your-namespace  # verify access

Port-forward timeout¶

ConfigurationError: Port-forward timed out for dev - port did not become available

Possible causes:

1. Service doesn't exist in the namespace
2. Network connectivity issues
3. Firewall blocking the connection

Debug steps:

# Verify the service exists
kubectl get svc -n unblu-dev

# Try manual port-forward
kubectl port-forward -n unblu-dev svc/haproxy 8084:8080

# Check for errors in kubectl output