How Kubernetes Context Switching Works in MCP Server Kubernetes Using kubectl_context

The kubectl_context tool in flux159/mcp-server-kubernetes enables runtime Kubernetes context switching by validating and executing kubectl config use-context, while the KubernetesManager class provides an internal setCurrentContext() API that rebuilds core API clients dynamically.

The flux159/mcp-server-kubernetes repository implements robust cluster context management through both environment variable initialization and dynamic tool invocation. Understanding how the kubectl_context tool and KubernetesManager class collaborate to switch contexts—validating target clusters, executing kubectl commands, and rebuilding API clients—is essential for managing multi-cluster environments through the MCP protocol.

Understanding the Context Switching Architecture

The server implements two complementary mechanisms for changing the active Kubernetes context: an internal programmatic API for server-side logic and an MCP tool interface for external requests.

KubernetesManager Internal API

The KubernetesManager class in src/utils/kubernetes-manager.ts provides the foundational context management logic. The setCurrentContext(name) method (lines 30‑52) performs the core switching operation:

• Reads available contexts from the loaded KubeConfig
• Verifies the requested context name exists
• Updates the current context in the configuration
• Rebuilds the three core API clients: CoreV1Api, AppsV1Api, and BatchV1Api

This ensures that all subsequent API calls use the correct cluster credentials and endpoint.

kubectl_context Tool Implementation

The kubectl_context tool is implemented in src/tools/kubectl-context.ts (lines 66‑99). When handling the case "set": operation, it:

1. Validates the target context exists by running kubectl config get-contexts -o name
2. Executes kubectl config use-context <name> to update the kubeconfig file
3. Returns a structured JSON payload confirming the switch

This approach ensures that context changes persist beyond the current process lifetime by modifying the actual kubeconfig file.

How Context Switching Works at Runtime

The server handles context changes through three distinct entry points:

Automatic initialization at startup. The KubernetesManager constructor checks for the K8S_CONTEXT environment variable (lines 85‑89 in src/utils/kubernetes-manager.ts). If present, it immediately calls setCurrentContext() to switch the active cluster before accepting tool requests.

Explicit user requests via MCP tools. When a client invokes kubectl_context with operation: "set", the tool validates the context name against available clusters, executes the kubectl command, and returns a confirmation payload.

Direct programmatic access. Other tools or server components can import KubernetesManager and call setCurrentContext() directly to switch contexts without spawning a kubectl subprocess, optimizing performance for frequent context changes.

Implementation Examples and Code Samples

Environment Variable Initialization

Set the active context before starting the server:

export K8S_CONTEXT=prod-cluster
npm run start

The server constructor automatically applies this context:

if (process.env.K8S_CONTEXT) {
  this.setCurrentContext(process.env.K8S_CONTEXT);
}

Runtime Context Switching via kubectl_context

Invoke the MCP tool to change contexts dynamically:

{
  "tool": "kubectl_context",
  "input": {
    "operation": "set",
    "name": "staging-cluster"
  }
}

The tool returns a structured confirmation:

{
  "content": [
    {
      "type": "text",
      "text": "{
  \"success\": true,
  \"message\": \"Current context set to 'staging-cluster'\",
  \"context\": \"staging-cluster\"
}"
    }
  ]
}

Programmatic Context Management

For server-side logic, use the manager directly:

import { KubernetesManager } from "./src/utils/kubernetes-manager";

const k8sMgr = new KubernetesManager();
await k8sMgr.setCurrentContext("dev-cluster"); // throws if context missing

This approach rebuilds the API clients immediately without executing shell commands.

Listing Available Contexts

Query available contexts before switching:

{
  "tool": "kubectl_context",
  "input": {
    "operation": "list",
    "output": "json",
    "showCurrent": true
  }
}

The tool parses kubectl config get-contexts output and returns an array of objects containing name, cluster, user, namespace, and isCurrent properties.

Summary

• The KubernetesManager constructor checks the K8S_CONTEXT environment variable on startup (lines 85‑89 in src/utils/kubernetes-manager.ts) and applies it automatically.
• The setCurrentContext() method validates context names against the loaded KubeConfig and rebuilds CoreV1Api, AppsV1Api, and BatchV1Api clients (lines 30‑52).
• The kubectl_context tool validates contexts via kubectl config get-contexts -o name before executing kubectl config use-context (lines 66‑99 in src/tools/kubectl-context.ts).
• Context switching works both at server initialization and dynamically during runtime without requiring process restarts when using the tool interface.

Frequently Asked Questions

What is the kubectl_context tool in MCP Server Kubernetes?

The kubectl_context tool is an MCP tool implemented in src/tools/kubectl-context.ts that wraps kubectl config commands to list, get, or set Kubernetes contexts dynamically during server runtime. It provides a standardized interface for clients to query and modify the active cluster configuration without direct filesystem access.

How does the server validate a context before switching?

Before executing kubectl config use-context, the tool runs kubectl config get-contexts -o name to retrieve a list of valid context names. It compares the requested context against this list, throwing an error if the target does not exist in the kubeconfig file. This prevents invalid context errors and ensures only configured clusters can be selected.

Can I set a default context when starting the MCP server?

Yes. Set the K8S_CONTEXT environment variable before starting the server. The KubernetesManager constructor in src/utils/kubernetes-manager.ts detects this variable during initialization (lines 85‑89) and automatically calls setCurrentContext() to establish the cluster connection before processing any tool requests.

Does switching contexts rebuild the Kubernetes API clients?

Yes. When KubernetesManager.setCurrentContext() is invoked—whether by the constructor, the kubectl_context tool, or direct programmatic calls—it updates the internal KubeConfig current context and rebuilds the CoreV1Api, AppsV1Api, and BatchV1Api clients (lines 30‑52 in src/utils/kubernetes-manager.ts). This ensures all subsequent API operations target the correct cluster.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}