Deploying vMCP Locally

This skill helps you deploy and test VirtualMCPServer configurations in a local Kind cluster for manual verification.

Prerequisites

Before using this skill, ensure you have:

Kind installed
kubectl installed
Task installed
Helm installed
A cloned copy of the toolhive repository

Instructions

1. Set up the local cluster

If no Kind cluster exists, create one with the ToolHive operator:

# From the toolhive repository root
task kind-with-toolhive-operator

This creates a Kind cluster named toolhive with:

Nginx ingress controller
ToolHive CRDs installed
ToolHive operator deployed

2. For development/testing with local changes

If you need to test local code changes:

# Set up cluster with e2e port mappings
task kind-setup-e2e

# Install CRDs
task operator-install-crds

# Build and deploy local operator image
task operator-deploy-local

3. Apply the VirtualMCPServer configuration

Apply the YAML configuration you want to test:

kubectl apply -f <path-to-vmcp-yaml> --kubeconfig kconfig.yaml

4. Verify deployment

Check the VirtualMCPServer status:

# List all VirtualMCPServers
kubectl get virtualmcpserver --kubeconfig kconfig.yaml

# Get detailed status
kubectl get virtualmcpserver <name> -o yaml --kubeconfig kconfig.yaml

# Check operator logs for issues
kubectl logs -n toolhive-system -l app.kubernetes.io/name=thv-operator --kubeconfig kconfig.yaml

5. Test the vMCP endpoint

For NodePort service type (useful for local testing):

# Get the NodePort
kubectl get svc vmcp-<name> -o jsonpath='{.spec.ports[0].nodePort}' --kubeconfig kconfig.yaml

# Test the endpoint (port will be on localhost when using kind-setup-e2e)
curl http://localhost:<nodeport>/mcp

For ClusterIP (default), use port-forward:

kubectl port-forward svc/vmcp-<name> 4483:4483 --kubeconfig kconfig.yaml
curl http://localhost:4483/mcp

6. Test MCP protocol

Use an MCP client to verify tool discovery and execution:

# Initialize MCP session
curl -X POST http://localhost:<port>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'

# List tools
curl -X POST http://localhost:<port>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

7. Clean up

When done testing:

# Remove specific resources
kubectl delete -f <path-to-vmcp-yaml> --kubeconfig kconfig.yaml

# Or destroy the entire cluster
task kind-destroy

Example YAML files

Reference example configurations are in examples/operator/virtual-mcps/:

File	Description
`vmcp_simple_discovered.yaml`	Basic discovered mode configuration
`vmcp_conflict_resolution.yaml`	Tool conflict handling strategies
`vmcp_inline_incoming_auth.yaml`	Inline authentication configuration
`vmcp_production_full.yaml`	Full production configuration
`composite_tool_simple.yaml`	Simple composite tool workflow
`composite_tool_complex.yaml`	Complex multi-step workflows
`composite_tool_with_elicitations.yaml`	Workflows with user prompts

Troubleshooting

VirtualMCPServer stuck in Pending phase

Check that:

The MCPGroup exists and is Ready
All backend MCPServers in the group are Running
The operator has permissions to create the vMCP deployment

kubectl describe virtualmcpserver <name> --kubeconfig kconfig.yaml
kubectl get mcpgroup --kubeconfig kconfig.yaml
kubectl get mcpserver --kubeconfig kconfig.yaml

Backend servers not discovered

Verify backend servers have the correct groupRef:

kubectl get mcpserver -o custom-columns=NAME:.metadata.name,GROUP:.spec.groupRef --kubeconfig kconfig.yaml

Authentication issues

For testing, use anonymous auth:

incomingAuth:
  type: anonymous
  authzConfig:
    type: inline
    inline:
      policies:
        - 'permit(principal, action, resource);'