Deploy with Kubernetes

Deploy WeaveMCP agents on Kubernetes for production-grade scalability, reliability, and management.

Prerequisites

Kubernetes cluster (1.19+)
kubectl configured to access your cluster
WeaveMCP account with virtual server created
Agent token generated from the web console

Quick Deployment

1. Create Namespace

kubectl create namespace weavemcp

2. Create Secret

Store your agent token securely:

kubectl create secret generic weavemcp-agent-secret \
  --from-literal=agent-token="your-agent-token-here" \
  --namespace=weavemcp

3. Create ConfigMap

Create mcp-servers-config.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: weavemcp-mcp-servers
  namespace: weavemcp
data:
  mcp-servers.json: |
    {
      "mcpServers": {
        "filesystem-server": {
          "command": "npx",
          "args": ["@modelcontextprotocol/server-filesystem", "/data"],
          "env": {
            "NODE_ENV": "production"
          }
        },
        "git-server": {
          "command": "npx",
          "args": ["@modelcontextprotocol/server-git", "/repos"],
          "env": {
            "GIT_AUTHOR_NAME": "WeaveMCP Agent",
            "GIT_AUTHOR_EMAIL": "agent@weavemcp.com"
          }
        }
      }
    }

Apply the ConfigMap:

kubectl apply -f mcp-servers-config.yaml

4. Create Deployment

Create agent-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: weavemcp-agent
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: weavemcp-agent
  template:
    metadata:
      labels:
        app: weavemcp-agent
    spec:
      containers:
      - name: weavemcp-agent
        image: weavemcp/agent:v1.0.0
        ports:
        - containerPort: 8080
          name: health
        - containerPort: 9090
          name: metrics
        env:
        - name: WEAVEMCP_AGENT_TOKEN
          valueFrom:
            secretKeyRef:
              name: weavemcp-agent-secret
              key: agent-token
        - name: WEAVEMCP_SERVER_URL
          value: "https://your-virtual-server.weavemcp.dev"
        - name: WEAVEMCP_LOG_LEVEL
          value: "info"
        - name: WEAVEMCP_HEALTH_CHECK_PORT
          value: "8080"
        - name: WEAVEMCP_METRICS_PORT
          value: "9090"
        volumeMounts:
        - name: mcp-config
          mountPath: /app/config
          readOnly: true
        - name: data-volume
          mountPath: /data
        - name: repos-volume
          mountPath: /repos
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 250m
            memory: 256Mi
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsNonRoot: true
          runAsUser: 1000
      volumes:
      - name: mcp-config
        configMap:
          name: weavemcp-mcp-servers
      - name: data-volume
        persistentVolumeClaim:
          claimName: weavemcp-data-pvc
      - name: repos-volume
        persistentVolumeClaim:
          claimName: weavemcp-repos-pvc
      securityContext:
        fsGroup: 1000

5. Create Persistent Volumes

Create persistent-volumes.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: weavemcp-data-pvc
  namespace: weavemcp
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: weavemcp-repos-pvc
  namespace: weavemcp
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: standard

6. Create Service

Create agent-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: weavemcp-agent-service
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  selector:
    app: weavemcp-agent
  ports:
  - name: health
    port: 8080
    targetPort: 8080
  - name: metrics
    port: 9090
    targetPort: 9090
  type: ClusterIP

7. Deploy Everything

kubectl apply -f persistent-volumes.yaml
kubectl apply -f agent-deployment.yaml
kubectl apply -f agent-service.yaml

Production Configuration

Horizontal Pod Autoscaler

Create hpa.yaml:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: weavemcp-agent-hpa
  namespace: weavemcp
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: weavemcp-agent
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Pod Disruption Budget

Create pdb.yaml:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: weavemcp-agent-pdb
  namespace: weavemcp
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: weavemcp-agent

Network Policy

Create network-policy.yaml:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: weavemcp-agent-network-policy
  namespace: weavemcp
spec:
  podSelector:
    matchLabels:
      app: weavemcp-agent
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: monitoring
    ports:
    - protocol: TCP
      port: 9090  # Metrics
  - from:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 8080  # Health checks
  egress:
  - to: []  # Allow all egress for WeaveMCP communication
    ports:
    - protocol: TCP
      port: 443
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53
    - protocol: UDP
      port: 53

Monitoring Integration

ServiceMonitor for Prometheus

Create service-monitor.yaml:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: weavemcp-agent-metrics
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  selector:
    matchLabels:
      app: weavemcp-agent
  endpoints:
  - port: metrics
    path: /metrics
    interval: 30s

Grafana Dashboard

Use our pre-built Grafana dashboard:

kubectl create configmap weavemcp-dashboard \
  --from-file=dashboard.json \
  --namespace=monitoring

Advanced Features

Multi-Region Deployment

Deploy across multiple regions for high availability:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: weavemcp-agent
  namespace: weavemcp
spec:
  replicas: 6
  template:
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app
                  operator: In
                  values:
                  - weavemcp-agent
              topologyKey: topology.kubernetes.io/zone
      # ... rest of spec

Custom Resource Definitions

Define custom MCP server configurations:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: mcpservers.weavemcp.com
spec:
  group: weavemcp.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              name:
                type: string
              command:
                type: string
              args:
                type: array
                items:
                  type: string
              env:
                type: object
                additionalProperties:
                  type: string
  scope: Namespaced
  names:
    plural: mcpservers
    singular: mcpserver
    kind: MCPServer

Operations

Health Monitoring

Check agent health:

# Check pod status
kubectl get pods -n weavemcp

# Check agent health endpoint
kubectl port-forward -n weavemcp svc/weavemcp-agent-service 8080:8080
curl http://localhost:8080/health

# View agent logs
kubectl logs -n weavemcp -l app=weavemcp-agent --tail=100

Scaling

Scale the deployment:

# Manual scaling
kubectl scale deployment weavemcp-agent --replicas=5 -n weavemcp

# Check HPA status
kubectl get hpa -n weavemcp

# View scaling events
kubectl describe hpa weavemcp-agent-hpa -n weavemcp

Updates

Rolling updates:

# Update image
kubectl set image deployment/weavemcp-agent \
  weavemcp-agent=weavemcp/agent:v1.1.0 \
  -n weavemcp

# Check rollout status
kubectl rollout status deployment/weavemcp-agent -n weavemcp

# Rollback if needed
kubectl rollout undo deployment/weavemcp-agent -n weavemcp

Backup and Restore

Backup persistent data:

# Create backup job
kubectl create job weavemcp-backup \
  --from=cronjob/weavemcp-backup-cronjob \
  -n weavemcp

# Check backup status
kubectl get jobs -n weavemcp

# List backups
kubectl exec -n weavemcp deployment/weavemcp-agent -- \
  ls -la /backups

Troubleshooting

Pods not starting

# Check pod events
kubectl describe pods -n weavemcp

# Check resource constraints
kubectl top pods -n weavemcp

# Verify secrets and configmaps
kubectl get secrets,configmaps -n weavemcp

Health checks failing

# Check service endpoints
kubectl get endpoints -n weavemcp

# Test health endpoint directly
kubectl exec -n weavemcp deployment/weavemcp-agent -- \
  curl http://localhost:8080/health

# Review probe configuration
kubectl describe deployment weavemcp-agent -n weavemcp

Network connectivity issues

# Test external connectivity
kubectl exec -n weavemcp deployment/weavemcp-agent -- \
  curl -I https://console.weavemcp.com

# Check network policies
kubectl get networkpolicies -n weavemcp

# Verify DNS resolution
kubectl exec -n weavemcp deployment/weavemcp-agent -- \
  nslookup console.weavemcp.com

Security Best Practices

Use specific image tags: Avoid latest in production
Run as non-root: Set runAsNonRoot: true
Read-only filesystem: Use readOnlyRootFilesystem: true
Resource limits: Always set CPU and memory limits
Network policies: Restrict network access
Secret management: Use external secret management systems
Pod security standards: Implement Pod Security Standards
Regular updates: Keep images and Kubernetes updated

Next Steps

Monitoring Setup

Set up comprehensive monitoring and alerting

Multi-Cluster

Deploy across multiple Kubernetes clusters

GitOps Integration

Manage deployments with GitOps workflows

Custom Operators

Build custom Kubernetes operators for WeaveMCP

Getting started

Agent Deployment

Development

Customization

Writing content

AI tools

Kubernetes

Deploy with Kubernetes

Prerequisites

Quick Deployment

1. Create Namespace

2. Create Secret

3. Create ConfigMap

4. Create Deployment

5. Create Persistent Volumes

6. Create Service

7. Deploy Everything

Production Configuration

Horizontal Pod Autoscaler

Pod Disruption Budget

Network Policy

Monitoring Integration

ServiceMonitor for Prometheus

Grafana Dashboard

Advanced Features

Multi-Region Deployment

Custom Resource Definitions

Operations

Health Monitoring

Scaling

Updates

Backup and Restore

Troubleshooting

Security Best Practices

Next Steps

Monitoring Setup

Multi-Cluster

GitOps Integration

Custom Operators

​Deploy with Kubernetes

​Prerequisites

​Quick Deployment

​1. Create Namespace

​2. Create Secret

​3. Create ConfigMap

​4. Create Deployment

​5. Create Persistent Volumes

​6. Create Service

​7. Deploy Everything

​Production Configuration

​Horizontal Pod Autoscaler

​Pod Disruption Budget

​Network Policy

​Monitoring Integration

​ServiceMonitor for Prometheus

​Grafana Dashboard

​Advanced Features

​Multi-Region Deployment

​Custom Resource Definitions

​Operations

​Health Monitoring

​Scaling

​Updates

​Backup and Restore

​Troubleshooting

​Security Best Practices

​Next Steps

Monitoring Setup

Multi-Cluster

GitOps Integration

Custom Operators

Deploy with Kubernetes

Prerequisites

Quick Deployment

1. Create Namespace

2. Create Secret

3. Create ConfigMap

4. Create Deployment

5. Create Persistent Volumes

6. Create Service

7. Deploy Everything

Production Configuration

Horizontal Pod Autoscaler

Pod Disruption Budget

Network Policy

Monitoring Integration

ServiceMonitor for Prometheus

Grafana Dashboard

Advanced Features

Multi-Region Deployment

Custom Resource Definitions

Operations

Health Monitoring

Scaling

Updates

Backup and Restore

Troubleshooting

Security Best Practices

Next Steps