Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.weavemcp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

# 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

# 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

# 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

  1. Use specific image tags: Avoid latest in production
  2. Run as non-root: Set runAsNonRoot: true
  3. Read-only filesystem: Use readOnlyRootFilesystem: true
  4. Resource limits: Always set CPU and memory limits
  5. Network policies: Restrict network access
  6. Secret management: Use external secret management systems
  7. Pod security standards: Implement Pod Security Standards
  8. 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