The Model Context Protocol (MCP) server provides AI assistants with comprehensive access to Forklift migration resources, enabling intelligent automation and assistance for migration planning, execution, and troubleshooting. This chapter covers complete MCP integration from basic setup to advanced AI-assisted workflows.

Overview: Providing AI Assistants Access to Migration Resources

What is the MCP Server?

The kubectl-mtv MCP server is a built-in component that exposes migration toolkit functionality through the Model Context Protocol, allowing AI assistants to:

• Read Operations: List resources, query inventory, monitor migrations, analyze configurations
• Write Operations: Create, delete, and patch providers, plans, mappings, hosts, and hooks
• Real-time Monitoring: Watch migration progress, analyze logs, troubleshoot issues
• Intelligent Planning: Assist with migration strategy, resource optimization, and best practices

Supported AI Assistants

The MCP server integrates with various AI platforms:

• Claude Desktop: Direct integration via configuration file or CLI
• Cursor IDE: Built-in MCP support for development workflows
• Custom Tools: Any MCP-compatible client using the MCP SDK
• Web Applications: HTTP-based integrations via Streamable HTTP mode

Security Model

Important Security Notice: The MCP server provides both read and write access to migration resources. Use with appropriate security considerations:

• Authentication is passed through from the kubectl context
• All RBAC permissions apply to MCP operations
• Write operations can modify cluster resources
• Network access follows Kubernetes cluster policies

Server Modes

Stdio Mode (Default)

Stdio mode is designed for direct AI assistant integration via standard input/output streams. This is the recommended mode for most AI integrations.

Basic Stdio Setup

# Start MCP server in stdio mode (default)
kubectl mtv mcp-server

Stdio Mode Characteristics

• Communication: Uses stdin/stdout for MCP protocol messages
• Security: Inherits kubectl authentication and permissions
• Performance: Direct process communication for low latency
• Use Cases: AI assistant integration, local development, automated tools
• Logging: Server status logged to stderr

Stdio Mode Output Example

Starting kubectl-mtv MCP server in stdio mode
Server is ready and listening for MCP protocol messages on stdin/stdout

HTTP Mode (Streamable HTTP)

HTTP mode runs an HTTP server using the Streamable HTTP transport defined by the MCP specification. This enables web-based integrations and remote access scenarios with true per-request authentication.

Basic HTTP Setup

# Start MCP server in HTTP mode
kubectl mtv mcp-server --http --host 127.0.0.1 --port 8080

Advanced HTTP Configuration

# HTTP mode with custom host and port
kubectl mtv mcp-server --http --host 0.0.0.0 --port 9090

# HTTP mode with TLS encryption
kubectl mtv mcp-server --http \
  --host 0.0.0.0 \
  --port 8443 \
  --cert-file /path/to/server.crt \
  --key-file /path/to/server.key

HTTP Mode Characteristics

• Communication: HTTP/HTTPS with Streamable HTTP transport (MCP spec 2025-03-26)
• Security: Optional TLS encryption, per-request bearer token authentication
• Performance: Network-based with HTTP overhead
• Use Cases: Web applications, remote access, multi-user scenarios
• Endpoint: /mcp endpoint for MCP protocol communication
• Authentication: Each HTTP POST carries its own headers, enabling token rotation

HTTP Mode HTTP Headers

In HTTP mode, the following HTTP headers are supported for per-request Kubernetes authentication:

Header	Description
Authorization: Bearer <token>	Kubernetes authentication token (passed to kubectl via --token flag)
X-Kubernetes-Server: <url>	Kubernetes API server URL (passed to kubectl via --server flag)

Each POST request carries its own headers, providing true per-request authentication. If headers are not provided, the server falls back to the default kubeconfig behavior.

Command Line Options

Complete Flag Reference

All MCP server flags are verified from the implementation:

Flag	Type	Default	Description
--http	boolean	false	Run in HTTP mode using Streamable HTTP transport
--host	string	127.0.0.1	Host address to bind to for HTTP mode
--port	string	8080	Port to listen on for HTTP mode
--cert-file	string	""	Path to TLS certificate file (enables TLS when used with –key-file)
--key-file	string	""	Path to TLS private key file (enables TLS when used with –cert-file)
--output-format	string	text	Default output format for commands: text (table) or json
--server	string	""	Kubernetes API server URL (passed to kubectl via –server flag)
--token	string	""	Kubernetes authentication token (passed to kubectl via –token flag)
--max-response-chars	int	0	Max characters for text output (0 = unlimited). Truncates long responses to help small LLMs stay within context window limits

Usage Examples

Development Mode

# Local development with default settings
kubectl mtv mcp-server

# Development with HTTP access
kubectl mtv mcp-server --http --host 127.0.0.1 --port 8080

Remote Cluster Authentication

Use --server and --token to connect to a remote cluster without relying on a local kubeconfig. These flags work in both stdio and HTTP modes:

# Stdio mode with explicit credentials (e.g., for AI assistant integration)
kubectl mtv mcp-server \
  --server https://api.prod-cluster.example.com:6443 \
  --token "$SERVICE_ACCOUNT_TOKEN"

# HTTP mode with explicit credentials
kubectl mtv mcp-server --http \
  --server https://api.prod-cluster.example.com:6443 \
  --token "$SERVICE_ACCOUNT_TOKEN"

Credential Precedence: HTTP headers (per-request) > CLI flags (--server/--token) > kubeconfig (implicit).

Production Mode

# Production with TLS encryption
kubectl mtv mcp-server --http \
  --host 0.0.0.0 \
  --port 443 \
  --cert-file /etc/ssl/certs/mcp-server.crt \
  --key-file /etc/ssl/private/mcp-server.key

# Production with TLS and explicit cluster credentials
kubectl mtv mcp-server --http \
  --host 0.0.0.0 \
  --port 443 \
  --cert-file /etc/ssl/certs/mcp-server.crt \
  --key-file /etc/ssl/private/mcp-server.key \
  --server https://api.prod-cluster.example.com:6443 \
  --token "$SERVICE_ACCOUNT_TOKEN"

# Production with custom port and security
kubectl mtv mcp-server --http \
  --host 10.0.0.100 \
  --port 9443 \
  --cert-file /secure/certificates/server.crt \
  --key-file /secure/certificates/server.key

Testing and Integration

# Test connectivity (POST to the /mcp endpoint)
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Test with authentication token
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Validate TLS configuration
openssl s_client -connect 127.0.0.1:8443 -servername mcp-server

How-To: Integrating with AI Assistants

Claude Desktop Integration

Method 1: Using Claude CLI (Recommended)

The Claude CLI provides the simplest integration method:

# Install Claude CLI (if not already installed)
# Follow instructions at https://claude.ai/cli

# Add kubectl-mtv MCP server
claude mcp add kubectl-mtv kubectl mtv mcp-server

# Verify installation
claude mcp list

Method 2: Manual Configuration

For environments without the Claude CLI, configure manually:

Step 1: Locate Claude Desktop Configuration

# macOS
open ~/Library/Application\ Support/Claude/

# Linux
ls ~/.config/Claude/

# Windows (PowerShell)
explorer $env:APPDATA\Claude\

Step 2: Edit Configuration File

Create or edit claude_desktop_config.json:

{
  "mcpServers": {
    "kubectl-mtv": {
      "command": "kubectl",
      "args": ["mtv", "mcp-server"],
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

Step 3: Advanced Claude Configuration

Using --server and --token flags for a remote cluster (no kubeconfig needed):

{
  "mcpServers": {
    "kubectl-mtv-remote": {
      "command": "kubectl",
      "args": [
        "mtv", "mcp-server",
        "--server", "https://api.prod-cluster.example.com:6443",
        "--token", "eyJhbGciOi..."
      ]
    }
  }
}

Using kubeconfig with environment variables:

{
  "mcpServers": {
    "kubectl-mtv-prod": {
      "command": "kubectl",
      "args": ["mtv", "mcp-server"],
      "env": {
        "KUBECONFIG": "/secure/kubeconfig/prod-cluster.yaml",
        "MTV_VDDK_INIT_IMAGE": "registry.company.com/vddk:latest"
      }
    },
    "kubectl-mtv-dev": {
      "command": "kubectl", 
      "args": ["mtv", "mcp-server"],
      "env": {
        "KUBECONFIG": "/dev/kubeconfig/dev-cluster.yaml"
      }
    }
  }
}

Step 4: Restart and Verify

# Restart Claude Desktop application

# Test configuration by asking Claude:
# "List all MTV providers in the cluster"
# "Show me the status of migration plans"
# "Help me create a migration plan for VMware VMs"

Cursor IDE Integration

Basic Cursor Setup

Step 1: Access MCP Settings

1. Open Cursor IDE
2. Navigate to Settings (Cmd/Ctrl + ,)
3. Search for “MCP” or find MCP in extensions/features
4. Click “Add Server” or “Configure MCP”

Step 2: Add kubectl-mtv Server

Configure the MCP server:

• Name: kubectl-mtv
• Command: kubectl
• Args: mtv mcp-server

Step 3: Advanced Cursor Configuration

For production environments with specific requirements:

• Name: kubectl-mtv-production
• Command: kubectl
• Args: mtv mcp-server
• Environment Variables:
  • KUBECONFIG: /path/to/prod-kubeconfig.yaml
  • MTV_VDDK_INIT_IMAGE: registry.company.com/vddk:8.0.2

Step 4: Verify Integration

Test the integration within Cursor:

# Ask in Cursor chat:
# "Show me all migration providers"
# "Create a migration plan for these VMs: web-01, web-02"
# "Check the status of plan production-migration"

Custom Integration Development

Python MCP Client (Stdio Mode)

#!/usr/bin/env python3
"""
Custom MCP client for kubectl-mtv integration
"""

import asyncio
import json
from mcp import StdioClient, ClientSession

async def main():
    # Create stdio client
    client = StdioClient(
        command="kubectl",
        args=["mtv", "mcp-server"]
    )
    
    async with client:
        session = await client.create_session()
        
        # List available tools
        tools = await session.list_tools()
        print("Available tools:", [tool.name for tool in tools])
        
        # Call a specific tool
        result = await session.call_tool(
            "get_providers",
            arguments={"namespace": "migrations"}
        )
        
        print("Providers:", json.dumps(result.content, indent=2))

# Run the client
if __name__ == "__main__":
    asyncio.run(main())

Python MCP Client (HTTP Mode)

#!/usr/bin/env python3
"""
HTTP-based MCP client for kubectl-mtv integration using Streamable HTTP
"""

import asyncio
import json
import os

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    # Get authentication credentials
    token = os.getenv("KUBERNETES_TOKEN")
    server = os.getenv("KUBERNETES_SERVER")

    # Build headers for per-request authentication
    headers = {}
    if token:
        headers["Authorization"] = f"Bearer {token}"
    if server:
        headers["X-Kubernetes-Server"] = server

    # Create HTTP client with auth headers
    async with httpx.AsyncClient(
        headers=headers,
        timeout=httpx.Timeout(30, read=300),
    ) as http_client:
        async with streamable_http_client(
            url="http://127.0.0.1:8080/mcp",
            http_client=http_client,
        ) as (read_stream, write_stream, _get_session_id):
            async with ClientSession(read_stream, write_stream) as session:
                await session.initialize()

                # List available tools
                tools = await session.list_tools()
                print("Available tools:", [t.name for t in tools.tools])

                # Monitor migration plans
                result = await session.call_tool(
                    "mtv_read",
                    arguments={
                        "command": "get plan",
                        "flags": {"namespace": "migrations"},
                    },
                )
                print("Migration plans:", result)

if __name__ == "__main__":
    asyncio.run(main())

JavaScript/TypeScript Integration

// MCP client for web applications using Streamable HTTP
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

interface KubeCredentials {
    token?: string;
    server?: string;
}

class MigrationDashboard {
    private client: Client;
    private serverUrl: string;
    private creds?: KubeCredentials;

    constructor(serverUrl: string, creds?: KubeCredentials) {
        this.serverUrl = serverUrl;
        this.creds = creds;
        this.client = new Client({
            name: 'migration-dashboard',
            version: '1.0.0',
        });
    }

    async connect(): Promise<void> {
        // Build headers for Kubernetes authentication
        const headers: Record<string, string> = {};
        if (this.creds?.token) {
            headers['Authorization'] = `Bearer ${this.creds.token}`;
        }
        if (this.creds?.server) {
            headers['X-Kubernetes-Server'] = this.creds.server;
        }

        const transport = new StreamableHTTPClientTransport(
            new URL(this.serverUrl),
            { requestInit: { headers } }
        );
        await this.client.connect(transport);
    }

    async getProviders(): Promise<any> {
        return await this.client.callTool({
            name: 'mtv_read',
            arguments: {
                command: 'get provider',
                flags: { namespace: 'migrations' },
            },
        });
    }

    async createPlan(planConfig: any): Promise<any> {
        return await this.client.callTool({
            name: 'mtv_write',
            arguments: planConfig,
        });
    }
}

// Usage
const dashboard = new MigrationDashboard(
    'https://mcp-server.company.com:8443/mcp',
    {
        token: process.env.KUBERNETES_TOKEN,
        server: process.env.KUBERNETES_SERVER,
    }
);

await dashboard.connect();
const providers = await dashboard.getProviders();
console.log('Available providers:', providers);

AI-Assisted Migration Workflows

Claude-Assisted Migration Planning

Interactive Migration Discovery

Ask Claude to help with migration planning:

Claude, help me plan a migration from VMware to OpenShift. Here's what I need:

1. List all VMware providers in my cluster
2. Show me VMs that are powered on and have more than 8GB memory
3. Create a migration plan for production web servers
4. Optimize the plan for performance

Claude can then:

• Query your inventory automatically
• Analyze VM configurations
• Suggest optimal migration strategies
• Generate migration plans with best practices

Migration Troubleshooting

Use Claude for intelligent troubleshooting:

Claude, my migration plan "prod-migration" is failing. Can you:

1. Check the plan status
2. Look at recent events
3. Analyze any error messages
4. Suggest solutions

Cursor IDE Development Integration

Code-Aware Migration Scripts

Cursor can help write migration automation scripts:

# Ask Cursor: "Write a script to automate batch migration creation"

import subprocess
import json
from typing import List, Dict

def create_batch_migration(
    provider: str,
    vm_filter: str,
    target_namespace: str,
    batch_size: int = 5
) -> List[str]:
    """
    Create multiple migration plans in batches
    Generated with Cursor + kubectl-mtv MCP integration
    """
    
    # Get VMs matching filter
    result = subprocess.run([
        "kubectl", "mtv", "get", "inventory", "vms", "--provider", provider,
        "--query", vm_filter,
        "-o", "json"
    ], capture_output=True, text=True)
    
    vms = json.loads(result.stdout)
    
    # Create batches
    batches = [vms[i:i+batch_size] for i in range(0, len(vms), batch_size)]
    plan_names = []
    
    for i, batch in enumerate(batches):
        plan_name = f"batch-migration-{i+1}"
        vm_names = [vm['name'] for vm in batch]
        
        # Create migration plan
        subprocess.run([
            "kubectl", "mtv", "create", "plan", "--name", plan_name,
            "--source", provider,
            "--target-namespace", target_namespace,
            "--vms", ",".join(vm_names)
        ])
        
        plan_names.append(plan_name)
    
    return plan_names

Advanced AI Workflows

Migration Optimization Assistant

Claude, analyze my migration environment and suggest optimizations:

1. Review all my providers and their configurations
2. Check current migration plans and their efficiency
3. Analyze resource utilization during migrations
4. Suggest improvements for:
   - Convertor pod placement
   - Network and storage mappings
   - Migration timing and scheduling
   - VDDK configuration

Compliance and Audit Assistant

Claude, help me ensure migration compliance:

1. Review all provider credentials and security settings
2. Check RBAC permissions for migration operations
3. Verify TLS configuration and certificate validation
4. Generate a compliance report for our SOC2 audit
5. Suggest security improvements

Security and Authentication

Authentication Flow

The MCP server uses kubectl’s existing authentication:

# Authentication is inherited from kubectl context
kubectl config current-context
kubectl auth whoami

# MCP server uses the same authentication
kubectl mtv mcp-server

Token-Based Authentication (HTTP Mode)

In HTTP mode, each POST request carries its own authentication headers, providing true per-request auth. This means token rotation works seamlessly – there is no stale token problem.

# Generate service account token
kubectl create serviceaccount mcp-user -n migrations
kubectl create token mcp-user -n migrations --duration=24h

# Test with curl (POST to /mcp endpoint)
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test with token and specific API server
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Kubernetes-Server: https://api.example.com:6443" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Header Authentication Details

The HTTP mode supports two HTTP headers for Kubernetes authentication:

Authorization Header

# Extract token from service account
TOKEN=$(kubectl create token mcp-user -n migrations)

# Use with curl (each request carries its own token)
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Use with service account token from pod
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

X-Kubernetes-Server Header

# Connect to a specific Kubernetes API server
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Kubernetes-Server: https://kubernetes.default.svc" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Combine with authentication for remote cluster access
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Kubernetes-Server: https://remote-cluster.example.com:6443" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Fallback Behavior

When headers are not provided:

• If Authorization header is missing: Uses credentials from the server’s kubeconfig
• If X-Kubernetes-Server header is missing: Uses the API server from the server’s kubeconfig
• If both headers are missing: Falls back entirely to the default kubeconfig

Secure Production Setup

# Service account for MCP server
apiVersion: v1
kind: ServiceAccount
metadata:
  name: mcp-server
  namespace: migration-tools
---
# RBAC permissions
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: mcp-server-role
rules:
- apiGroups: ["forklift.konveyor.io"]
  resources: ["*"]
  verbs: ["get", "list", "create", "update", "patch", "delete", "watch"]
- apiGroups: [""]
  resources: ["secrets", "configmaps"]
  verbs: ["get", "list", "create", "update", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: mcp-server-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: mcp-server-role
subjects:
- kind: ServiceAccount
  name: mcp-server
  namespace: migration-tools

Troubleshooting MCP Integration

Common Issues and Solutions

MCP Server Not Starting

# Check kubectl connectivity
kubectl cluster-info
kubectl auth whoami

# Verify kubectl-mtv installation
kubectl mtv version

# Check MCP server logs
kubectl mtv mcp-server -v=2

AI Assistant Cannot Connect

# Verify server is running
ps aux | grep "kubectl.*mtv.*mcp-server"

# Test stdio communication
echo '{"method": "ping"}' | kubectl mtv mcp-server

# Test HTTP endpoint
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Authentication Issues

# Check current kubectl context
kubectl config current-context

# Verify permissions
kubectl auth can-i get providers.forklift.konveyor.io
kubectl auth can-i create plans.forklift.konveyor.io

# Test with explicit kubeconfig
KUBECONFIG=/path/to/config kubectl mtv mcp-server

Performance Issues

# Monitor resource usage
top -p $(pgrep -f "kubectl.*mtv.*mcp-server")

# Increase verbosity for debugging
kubectl mtv mcp-server -v=3

# Check for network issues (HTTP mode)
netstat -tlnp | grep 8080

Optimizing for Small Language Models

Small language models (< 30B parameters) may struggle with structured multi-turn tool use. The MCP server includes several built-in features to help, and there are client-side tuning options as well.

Common Problems

Small models can exhibit these failure modes when using MCP tools:

• CLI command mimicry: The model generates raw CLI strings instead of structured {command, flags} tool calls
• Hallucinated tool results: The model fabricates output and embeds it into the next call
• Format regression: The model falls back to its native tool-calling delimiters instead of the MCP protocol

Server-Side Mitigations

The MCP server automatically strips CLI command echoes from tool responses and validates input with corrective error messages. These are enabled by default and require no configuration.

To limit response sizes (preventing long outputs from overwhelming the model’s context window), use the --max-response-chars flag:

# Limit responses to 4000 characters (good starting point for small models)
kubectl mtv mcp-server --max-response-chars 4000

The default is 0 (unlimited – no truncation). When a response is truncated, the server appends a hint:

[truncated at 4000 chars. Use flags: {output: "json"} with fields: ["name", "id"] to get specific data]

Client-Side Inference Settings

Configure these in your LLM hosting platform or client application:

Setting	Recommended Value	Why
temperature	0.0 - 0.1	Minimizes format drift and hallucinated outputs
max_tokens	1000 - 2000	Prevents runaway generation mixing reasoning and garbled tool calls
parallel_tool_calls	false	Forces one tool call at a time, reducing confusion
tool_choice	"auto"	Prevents mixing free-form text with tool-call syntax

Example: Small Model Configuration

{
  "mcpServers": {
    "kubectl-mtv": {
      "command": "kubectl",
      "args": ["mtv", "mcp-server", "--max-response-chars", "4000"]
    }
  }
}

Best Practices for MCP Integration

Security Best Practices

1. Use Least Privilege: Configure RBAC with minimal required permissions
2. Enable TLS: Use certificate-based encryption for HTTP mode
3. Monitor Access: Log and audit MCP server usage
4. Rotate Tokens: Regularly rotate service account tokens
5. Network Security: Restrict MCP server network access

Performance Optimization

1. Use Stdio Mode: For direct AI integrations, stdio mode is more efficient
2. Limit Concurrency: Avoid simultaneous large operations
3. Cache Results: Cache inventory queries in AI applications
4. Monitor Resources: Watch CPU and memory usage during operations
5. Optimize Queries: Use specific filters in inventory queries

Operational Excellence

1. Document Integration: Maintain clear AI integration documentation
2. Version Control: Track MCP configuration changes
3. Test Regularly: Validate AI assistant functionality
4. Monitor Health: Implement MCP server health checks
5. Backup Configuration: Maintain backup of AI integration configs

Next Steps

After mastering MCP integration:

1. Complete Migration Toolkit: Explore complementary tools in Chapter 23: Integration with KubeVirt Tools

---

Previous: Chapter 21: Best Practices and Security
Next: Chapter 23: Integration with KubeVirt Tools