Deploy MCP hub with Helm and agent integration

Introduction

When you need to run an MCP tool registry reliably across many agents, a single-pod deployment is fragile — one pod restart takes every agent offline and nothing is tracking tool resolution latency or cache health. Helm solves this by templating the full Kubernetes stack — deployment, service, ingress, service monitor, and config — so you can promote the same chart from staging to production by swapping a single values file. By the end of this lesson, you'll be able to write a production values file that configures replica count, resource limits, probe timing, connection pool sizing, and Prometheus monitoring for the MCP hub, and deploy the entire registry with a single helm install command.

Key Terminology

• Helm values file — an environment-specific YAML file (e.g., values-production.yaml) that overrides chart defaults for a given deployment target, letting you promote the same chart from staging to production by swapping one file passed to helm install --values.
• replicaCount — the number of MCP hub pod replicas Kubernetes maintains simultaneously; setting this to 3 distributes traffic across failure domains so a single pod restart does not take the registry offline for every connected agent.
• readinessProbe.initialDelaySeconds — a per-pod delay before Kubernetes begins health-checking the container, sized to give the MCP hub time to load the full tool catalog and warm the ACL policy cache before agent traffic is routed to it.
• toolVersioning.strictSemver — a chart flag that, when true, prevents agents from resolving tool versions across breaking semver boundaries; set to false in staging for compatibility testing and true in production to guard against accidental breaking-version resolution.
• database.pool.maxConnections — the ceiling on concurrent database connections opened across all hub pods, calculated as replicaCount × concurrent resolution requests per pod (e.g., 3 × 10 = 30) to prevent connection exhaustion under burst load.
• metrics.serviceMonitor — a Prometheus ServiceMonitor resource emitted by the chart when metrics.serviceMonitor.enabled: true, which directs Prometheus to scrape tool resolution latency and cache hit rate from every MCP hub pod automatically.

Concepts

Helm as an Environment Promotion Contract

A single MCP hub chart can back staging and production deployments without any structural changes — only the values file differs. This is Helm's core value for the registry: the chart is a parameterized blueprint, and values-production.yaml is the environment contract that fills in the production-specific decisions. When you run helm install mcp-hub ./chart --values values-production.yaml, Helm renders the full Kubernetes object graph — Deployment, Service, Ingress, ConfigMap, and ServiceMonitor — from those values in one atomic operation. Promoting from staging to production becomes a diff between two values files rather than a runbook of manual kubectl commands that can drift.

This means every production stability decision should live in the values file and nowhere else. Replica count, resource limits, probe timing, feature flags, and connection pool sizing all belong here — not in ad-hoc kubectl patch commands applied after the fact.

Readiness Probe Timing and Catalog Load

Kubernetes routes traffic to a pod the moment its readiness probe succeeds. For the MCP hub, a probe that passes before the full tool catalog is loaded means agents receive incomplete resolution results — a silent failure that is harder to detect than the pod simply being unavailable. Setting readinessProbe.initialDelaySeconds: 30 creates a mandatory window before the first probe fires, giving each pod time to load the catalog and warm its ACL policy cache before it accepts traffic.

This delay is not a fixed magic number: it grows linearly with the number of registered tools in the catalog, so it must be revisited as the registry expands. The failureThreshold: 3 paired with periodSeconds: 10 then provides a 30-second tolerance window for transient slowness after the initial delay expires. These three fields together form a load-aware readiness gate — not a simple liveness check (see Code Walkthrough).

Connection Pool Sizing

The MCP hub's database connection pool must be sized as a product of two numbers: the replica count and the maximum number of concurrent tool resolution requests each pod will handle. With replicaCount: 3 and ten concurrent resolution requests per pod, the correct pool ceiling is 3 × 10 = 30, expressed as database.pool.maxConnections: 30. Setting this value too low causes connection exhaustion — pods queue requests behind busy connections during traffic spikes, producing errors for agents. Setting it too high wastes PostgreSQL backend memory allocated across every replica.

The values file makes this relationship explicit and auditable: when replicaCount changes in a scale-up event, maxConnections must be updated in the same edit so the pool math stays correct (see Code Walkthrough).

Prometheus Observability via ServiceMonitor

Enabling metrics.serviceMonitor.enabled: true causes the chart to emit a Kubernetes ServiceMonitor custom resource alongside the Deployment. The Prometheus Operator discovers this resource automatically and begins scraping tool resolution latency and cache hit rate from every hub pod's metrics endpoint — no manual scrape job configuration required. Because this wiring is inert in clusters without the Prometheus Operator, it defaults to false in the chart and is explicitly opted into through the production values file. The result is that observability is part of the deployment contract, not a post-deployment step that gets skipped under pressure.

Code Walkthrough

Now that you understand the Helm values patterns that drive production stability, let's walk through a complete deployment of the MCP hub.

The values file is where each configuration decision from the Concepts section becomes concrete. A production values-production.yaml for the MCP hub sets replica count, resource limits, probe timing, connection pool sizing, and monitoring in one place:

Code snippetyaml
1replicaCount: 3
2
3resources:
4  requests:
5    memory: "512Mi"
6    cpu: "250m"
7  limits:
8    memory: "1Gi"
9    cpu: "1000m"
10
11readinessProbe:
12  initialDelaySeconds: 30
13  periodSeconds: 10
14  failureThreshold: 3
15
16toolVersioning:
17  strictSemver: true
18
19database:
20  pool:
21    maxConnections: 30  # replicaCount × 10 concurrent resolution requests per pod
22
23metrics:
24  serviceMonitor:
25    enabled: true

replicaCount: 3 distributes pods across failure domains for high availability. readinessProbe.initialDelaySeconds: 30 gives each pod time to load the full tool catalog before Kubernetes routes agent traffic to it — this delay grows linearly with the number of registered tools, so tune it upward as the catalog expands. database.pool.maxConnections: 30 accounts for three replicas each handling up to ten concurrent resolution requests; setting this too low causes connection exhaustion under burst load. toolVersioning.strictSemver: true prevents agents from accidentally resolving across breaking version boundaries in production; staging environments can set this to false for broader compatibility testing. metrics.serviceMonitor.enabled: true wires Prometheus to scrape tool resolution latency and cache hit rate from every pod.

With the values file in place, install the chart and wait for all replicas to pass their readiness probes:

Code snippetbash
1helm install mcp-hub ./chart \
2  --namespace tools \
3  --create-namespace \
4  --values values-production.yaml \
5  --wait \
6  --timeout 5m
7
8kubectl rollout status deployment/mcp-hub-api -n tools
9kubectl get pods -n tools -l app=mcp-hub

helm install with --wait blocks until every pod reports ready, so the command exits successfully only after readiness probes confirm the catalog is loaded and the ACL policy cache is warm. kubectl rollout status then verifies the deployment is stable, and kubectl get pods shows whether all three replicas reached Running state.

Confirm that all three MCP hub pods show Running status and that kubectl get pods reports zero restarts before routing any agents to the registry.

Do's and Don'ts

Having walked through the values file, install command, and verification steps, the following rules distill the production-deployment patterns that most often determine whether the MCP hub stays stable under agent load.

Do's

1. ✓Do set database.pool.maxConnections as a multiple of replicaCount — each pod handles up to ten concurrent tool resolution requests, so a three-replica deployment requires at least 30 connections; sizing this too low causes connection exhaustion under burst load when agents hit the registry simultaneously.
2. ✓Do tune readinessProbe.initialDelaySeconds upward as the tool catalog grows — Kubernetes routes agent traffic to a pod the moment it passes the readiness probe, so a delay that is too short sends requests to pods that haven't finished loading the full catalog and ACL policy cache, returning resolution errors to agents.
3. ✓Do use --wait and --timeout with helm install and follow with kubectl rollout status — --wait blocks until every replica passes its readiness probe, making the install command a reliable gate; confirming zero restarts with kubectl get pods -n tools -l app=mcp-hub before routing agents ensures the registry is fully stable, not just partially up.

Don'ts

1. ✗Don't enable toolVersioning.strictSemver: false in a production values-production.yaml — disabling strict semver in production lets agents silently resolve tools across breaking version boundaries, causing unpredictable behavior; reserve false for staging environments where broader compatibility testing is intentional.
2. ✗Don't omit metrics.serviceMonitor.enabled: true from the production values file — without the service monitor, Prometheus cannot scrape tool resolution latency or cache hit rate from any of the three pods, leaving you blind to the connection pool saturation and probe-timing regressions that are the most common causes of registry outages.
3. ✗Don't route agents to the MCP hub registry before all three pods show Running with zero restarts — a pod that restarted after helm install --wait exited may have crashed post-readiness, meaning its tool catalog load or ACL cache warm-up failed; sending agent traffic to it at that point results in intermittent resolution failures that are hard to reproduce and trace back to the deployment.