Deploy with Helm¶

How to install the adapter on Kubernetes using the published Helm chart, which deployment shape to choose, and what the commands actually look like.

Why use this path¶

Helm is the right path when you want Kubernetes to own the boring parts for you: rollout mechanics, pod restarts, ingress wiring, persistent volumes, and predictable upgrades.

It is a good fit when you want:

repeatable cluster installs and upgrades
ingress and service configuration
persistent or shared storage
pod-level security and runtime controls
either colocated upstream sidecars or separately managed upstream services

For end users, the thing to share is the published Helm repository URL:

https://aakashh242.github.io/remote-mcp-adapter

That is the GitHub Pages root where Helm reads index.yaml. It is the correct URL for helm repo add. The source chart folder is useful for contributors, but it is not the main install entry point.

Prerequisites¶

Before you install the chart, make sure you have:

a Kubernetes cluster
Helm 3
a namespace plan
a values-file strategy
storage planned correctly for your chosen shape

Redis is not a universal prerequisite for every Helm scenario. The durable standalone and simple distributed examples in this guide use disk-backed state. Redis becomes a real prerequisite once you want multiple adapter replicas sharing session metadata — specifically the HA adapter tier shape.

If users will call <server_id>_get_upload_url(...) or open HTTP artifact download links through ingress, plan core.public_base_url up front. In Kubernetes that usually means the public hostname exposed by your ingress or load balancer. Without it, helper-generated URLs can point at an internal service or pod address instead of the address your client actually reaches.

Also note the supported Kubernetes range from charts/remote-mcp-adapter/Chart.yaml:

Kubernetes >= 1.29.0
Kubernetes < 1.36.0

How to think about Helm scenarios¶

The chart has two core topology knobs:

deploymentMode: standalone
deploymentMode: distributed

But that is only the start. In practice, most teams choose a Kubernetes operating shape, not just a raw mode flag.

The scenarios that tend to matter in the real world:

standalone quick start
standalone durable service
distributed shared platform
HA adapter tier
browser-facing ingress
observability-first production

These are deployment shapes, not replacements for the runtime config scenarios in Configuration. The goal here is to show the Helm values you would actually apply in Kubernetes.

One important distinction before you pick:

Base shapes are complete starting points you can install directly.
Overlays are additive values files you usually layer on top of a base shape with multiple -f flags.

In this section:

Base shapes: Standalone Quick Start, Standalone Durable Service, Distributed Shared Platform, HA Adapter Tier
Overlays: Browser-Facing Ingress, Observability-First Production

Helm deployment scenarios¶

Each deployment shape has its own dedicated page so you can jump straight to the one that matches your cluster without wading through every other pattern first.

Standalone Quick Start — the simplest one-release Kubernetes entry point.
Standalone Durable Service — standalone, but with ingress, persistence, and stronger defaults.
Distributed Shared Platform — separate adapter lifecycle from upstream service lifecycle.
HA Adapter Tier — multiple adapter replicas with Redis-backed state and shared storage.
Browser-Facing Ingress — overlay values for human-clickable links and browser-facing flows.
Observability-First Production — overlay values for telemetry-heavy operated environments.

Each page follows the same pattern:

what the shape is for
a realistic values.yaml example
the commands to run with helm repo add, helm repo update, and helm upgrade --install
links to the matching runtime-config guidance when you need more than chart values

For the cleanest reading experience:

Choose a Shape
one base shape page
optional overlay pages
optional Example Values Files if you want checked-in copy-paste starters
Layered values-file pairs
Post-Install Verification

Not sure where to start? Use this shortcut:

choose Standalone Quick Start if you want the easiest cluster trial
choose Standalone Durable Service if one pod is still enough, but the service is now real
choose Distributed Shared Platform if upstreams already live elsewhere
choose HA Adapter Tier if you need real adapter resilience
choose Browser-Facing Ingress if humans will click returned links
choose Observability-First Production if telemetry and operations are first-class concerns

When a local chart checkout is useful¶

Installing from charts/remote-mcp-adapter is mainly useful when:

you are testing unreleased chart changes
you are contributing to the chart itself
you want to inspect the chart source before publishing

That is a contributor path, not the primary end-user path.

Common Helm mistakes¶

Shared storage planned incorrectly

In both standalone and distributed shapes, the adapter and any file-producing or file-consuming upstream must agree on the same shared storage path.

Choosing distributed mode without solving file access

Shared metadata alone is not enough. Upload and artifact file content still has to live on storage that the relevant services can reach.

Assuming Redis is either always required or never required

Redis is scenario-specific. Single-replica shapes can work with disk-backed state, but multi-replica adapter deployments need a shared state backend such as Redis.

Treating chart values as separate from adapter config

The chart renders the adapter config into a ConfigMap. The Kubernetes values and the adapter's runtime config are connected, not independent.

Forgetting public_base_url once ingress is doing the real routing

If clients rely on helper-generated upload URLs or HTTP artifact download links, core.public_base_url needs to match the external hostname they actually use.

Forgetting secret-backed environment variables

If your config uses ${ENV_VAR} interpolation, the adapter container needs those variables injected. The chart now supports both explicit environment.env values and secret-backed environment.envFromSecret loading.

Using local chart installs as the default docs path

For end users, the published Helm repository is the simpler and more stable story.

What to do after install¶

After any scenario install: check pod readiness, check the service or ingress address, hit /healthz, and confirm the configured upstream server shows as healthy.

kubectl get pods -n remote-mcp-adapter
kubectl get svc -n remote-mcp-adapter
kubectl logs -n remote-mcp-adapter deploy/remote-mcp-adapter

Next steps¶

Previous topic: Deploy with Docker Compose — the simpler single-machine path.
Next: Choose a Shape — decide which Helm story actually fits before you install.
See also: Deployment — deployment overview and path selection.
See also: Configuration — choose the runtime behavior that fits the cluster shape you picked.