> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/ai-agent-access/on-premise-setup/deploy-on-kubernetes-with-helm.md).

# Deploy on Kubernetes with Helm

Install the MCP Gateway in a Kubernetes cluster that you run on your own servers, with Cakewalk's Helm chart, your PostgreSQL and your Redis.

This page installs the MCP Gateway in your own Kubernetes cluster with Cakewalk's Helm chart. Your Agents' tool calls, the stored credentials and the audit records then stay in your infrastructure. Your Admins still manage Connections and Policies in Cakewalk, and your Employees still sign in there.

The guide is written for a cluster that several teams share: a platform team owns the ingress and the network rules, and an application team installs into its own namespace. Running on AWS without the chart? See [Deploy on AWS](https://www.cakewalk.security/docs/ai-agent-access/on-premise-setup/deploy-on-aws.md).

***

### 📖 Key concepts

* **On-premise MCP Gateway**: The same MCP Gateway that Cakewalk runs in its cloud, installed in your cluster and serving your company only.
* **Policy engine**: A second container (OPA) in the gateway's pod. It evaluates every tool call against your Policies.
* **Configuration routes**: The routes under `/api/v1` that Cakewalk's cloud calls to send Connections and Policies to your gateway. Only Cakewalk's addresses may reach them.
* **Employee routes**: The routes that Agents and browsers use, such as `/mcp`. They require an Employee's token.

:bulb: *Why this matters*: With the gateway in your cluster, no tool call, credential or audit record leaves your network. Cakewalk only sends configuration to it.

***

### 🧭 What runs where

* **In your cluster:** one pod with two containers, the MCP Gateway and its policy engine. It needs a PostgreSQL database and a Redis, which you run.
* **At Cakewalk:** the identity provider where your Employees sign in, and the app where your Admins manage Connections and Policies. Cakewalk calls your gateway over HTTPS to send it that configuration.

The examples use placeholder names: the host `mcp.example.com`, the namespace `mcp-gateway` and the registry `registry.example.com`.

***

### 📦 What Cakewalk gives you

| Item                                                                                                 | Used in        |
| ---------------------------------------------------------------------------------------------------- | -------------- |
| A registry account (name and token) for `quay.io`                                                    | Step 2         |
| The chart version to install, for example `1.1.0`, and its image version, for example `2026.11.18.1` | Steps 2 and 10 |
| An API key and an API secret for the calls from Cakewalk                                             | Step 8         |
| The secret of the registration client                                                                | Step 8         |
| The source addresses of Cakewalk's calls                                                             | Steps 5 and 6  |

Cakewalk's configuration calls come from a fixed set of source addresses. Cakewalk gives them to you with the items above.

***

### ✅ What you need

* Kubernetes with x86-64 nodes. The gateway image has no ARM build.
* Helm 3.8 or later.
* One way in for HTTPS traffic: Istio with the Gateway API, or ingress-nginx.
* PostgreSQL 16 or later. We recommend version 18.
* Redis 7, dedicated to the gateway, with TLS and a password. One instance or cluster mode. Sentinel is not supported.
* A certificate for the gateway's host from a public certificate authority. Cakewalk's cloud and every Agent must trust it.
* Outbound HTTPS from the gateway to the internet, because it talks to Cakewalk's identity provider and to the third-party MCP servers of your Connections. If you use no cloud MCP servers, you can restrict this traffic: Cakewalk gives you the domains to allow.
* Inbound HTTPS to the gateway's host from Cakewalk's addresses, and from every place where your Employees' Agents run.

{% hint style="info" %}
An Agent that is a cloud service, such as ChatGPT or Claude on the web, connects from its provider's servers and not from the Employee's machine. To support those Agents, the gateway's host must be reachable from the internet. Agents on Employees' machines, such as Claude Code or Cursor, only need your internal network and your VPN.
{% endhint %}

***

### 🛠 Install

#### 1. Create the namespace

*Platform team.* The gateway's pod meets the `restricted` pod security level. Do not turn on Istio sidecar injection for this namespace.

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: mcp-gateway
  labels:
    pod-security.kubernetes.io/enforce: restricted
```

Save it as `namespace.yaml` and apply it:

```sh
kubectl apply -f namespace.yaml
```

#### 2. Get the images and the chart

*Platform team.* Choose one of the two.

{% tabs %}
{% tab title="Pull from quay.io" %}
Create a pull secret with the account that Cakewalk gave you:

```sh
kubectl -n mcp-gateway create secret docker-registry cakewalk-registry \
  --docker-server=quay.io --docker-username='<account>' --docker-password='<token>'
```

The machine that runs `helm` logs in too:

```sh
helm registry login quay.io -u '<account>'
```

The chart address for the next steps is `oci://quay.io/cakewalk/cakewalk-mcp-gateway`.
{% endtab %}

{% tab title="Copy to your registry" %}

```sh
skopeo login quay.io -u '<account>'
skopeo login registry.example.com

skopeo copy docker://quay.io/cakewalk/mcp-gateway:2026.11.18.1 \
            docker://registry.example.com/cakewalk/mcp-gateway:2026.11.18.1
skopeo copy docker://quay.io/cakewalk/opa:1.22.4-static \
            docker://registry.example.com/cakewalk/opa:1.22.4-static

helm registry login quay.io -u '<account>'
helm pull oci://quay.io/cakewalk/cakewalk-mcp-gateway --version 1.1.0
helm push cakewalk-mcp-gateway-1.1.0.tgz oci://registry.example.com/cakewalk
```

Keep the two image names and tags as they are. The chart builds each image address from the registry, the name and the tag.

The chart address for the next steps is `oci://registry.example.com/cakewalk/cakewalk-mcp-gateway`.
{% endtab %}
{% endtabs %}

#### 3. Prepare PostgreSQL

*Database team.* The script below creates the login role `mcp_gateway`, the database `mcp_gateway` owned by that role, and the schemas `api` and `audit_log`. No extension is needed. The gateway creates and upgrades its own tables when it starts.

Save it as `create-database.sql`:

```sql
\set ON_ERROR_STOP on

\if :{?gateway_password}
\else
  \echo 'Set the password of the new role: -v gateway_password=...'
  DO $$ BEGIN RAISE EXCEPTION 'gateway_password is not set'; END $$;
\endif

CREATE ROLE mcp_gateway LOGIN PASSWORD :'gateway_password';
GRANT mcp_gateway TO CURRENT_USER;
CREATE DATABASE mcp_gateway OWNER mcp_gateway;
REVOKE ALL ON DATABASE mcp_gateway FROM PUBLIC;

\connect mcp_gateway

CREATE SCHEMA api AUTHORIZATION mcp_gateway;
CREATE SCHEMA audit_log AUTHORIZATION mcp_gateway;
```

Run it once, as a role that can create roles and databases:

```sh
psql "host=postgres.example.com port=5432 dbname=postgres user=<admin> sslmode=verify-full" \
  -v gateway_password='<password>' -f create-database.sql
```

The connection string for step 8:

```
Host=postgres.example.com;Port=5432;Database=mcp_gateway;Username=mcp_gateway;Password=<password>;SSL Mode=VerifyFull
```

Choose a password without `;` and without quotes, because the connection string separates its parts with `;`.

#### 4. Prepare Redis

*Platform team.* The gateway keeps short-lived state in Redis, so it needs no persistence. It must not share the instance with other applications.

The connection string for step 8:

```
redis.example.com:6379,password=<password>,ssl=true,abortConnect=false
```

Choose a password without `,`, because the connection string separates its parts with `,`.

#### 5. Prepare the way in

*Platform team.* Point the DNS name `mcp.example.com` at your ingress, for your Employees and for the internet. Then prepare the ingress for the mode you use.

{% tabs %}
{% tab title="Istio with the Gateway API" %}
Your Gateway needs an HTTPS listener that covers `mcp.example.com`, with its certificate, and that accepts routes from the `mcp-gateway` namespace. A wildcard listener that you already have, such as `*.example.com`, is enough: use its name in step 9.

Otherwise, store the certificate as a Secret in the namespace of the Gateway:

```sh
kubectl -n istio-ingress create secret tls mcp-gateway-tls \
  --cert=mcp.example.com.crt --key=mcp.example.com.key
```

Then add the listener to your Gateway. Save this as `listener.yaml`:

```yaml
- op: add
  path: /spec/listeners/-
  value:
    name: mcp-gateway
    hostname: mcp.example.com
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
        - name: mcp-gateway-tls
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: mcp-gateway
```

```sh
kubectl -n istio-ingress patch gateway shared-gateway --type=json --patch-file listener.yaml
```

When the Gateway comes from a Git repository or a Helm chart of yours, add the content of `value` to its `listeners` there instead, or your tool reverts the patch.

Check the listener:

```sh
kubectl -n istio-ingress get gateway shared-gateway \
  -o jsonpath='{range .status.listeners[*]}{.name}: {.conditions[?(@.type=="Programmed")].status}{"\n"}{end}'
# mcp-gateway: True
```

`False` means that the Secret is missing, has another name, or is in another namespace.
{% endtab %}

{% tab title="ingress-nginx" %}
Store the certificate as a Secret in the gateway's namespace. The chart's Ingress uses it.

```sh
kubectl -n mcp-gateway create secret tls mcp-gateway-tls \
  --cert=mcp.example.com.crt --key=mcp.example.com.key
```

{% hint style="warning" %}
The ingress-nginx project is retired upstream. Cakewalk supports this mode for clusters that still run it, and recommends the Gateway API for new installations.
{% endhint %}
{% endtab %}
{% endtabs %}

**The source address.** The gateway accepts Cakewalk's configuration calls from Cakewalk's addresses only. That works only if your ingress knows where each request comes from.

* When a load balancer or a reverse proxy in front of the ingress adds `X-Forwarded-For`, configure the ingress to trust it. In Istio, set `numTrustedProxies` in the Gateway's `proxy.istio.io/config` annotation. In ingress-nginx, set `use-forwarded-headers` and `proxy-real-ip-cidr` in the controller's ConfigMap.
* When the Service of the ingress is of type `LoadBalancer` or `NodePort` with `externalTrafficPolicy: Cluster`, which is the default, Kubernetes replaces the source address with the address of a node. Set it to `Local`.

{% hint style="warning" %}
Check which address your ingress sees before you go on. Send one request from a machine whose public address you know, and read the access log of the ingress. It must show the address of that machine. The address of a node, of a pod or of a proxy means that one of the two cases above applies, and Cakewalk's calls will be rejected.
{% endhint %}

**Traffic from the internet.** When the host is open to the internet, two points apply to whatever stands in front of the ingress, such as a firewall or a WAF:

* **Limit the request rate on `/dcr`.** An Agent registers itself there before any Employee signs in, so the route accepts requests without a token. A limit per source address is enough.
* **Do not buffer or cut the connections on `/mcp` and `/meta`.** They are streams that stay open for minutes. Allow an idle time of at least 10 minutes.

Opening the host to the internet does not open the configuration routes. They stay limited to Cakewalk's addresses, whatever your perimeter allows.

#### 6. Allow the network traffic

*Platform team.* Only if your namespaces deny traffic by default. The gateway's pod needs:

| Direction | Peer                                 | Port |
| --------- | ------------------------------------ | ---- |
| Inbound   | The pods of your ingress             | 8080 |
| Outbound  | DNS                                  | 53   |
| Outbound  | PostgreSQL                           | 5432 |
| Outbound  | Redis                                | 6379 |
| Outbound  | The internet, or your outbound proxy | 443  |

The pod carries the label `app.kubernetes.io/name: mcp-gateway`. The two containers talk to each other inside the pod and need no rule.

#### 7. Generate the two key pairs

*Application team.* One pair signs the OAuth authorization codes. The other encrypts the credentials that the gateway stores for your Employees.

```sh
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out auth-code-private.pem
openssl pkey -in auth-code-private.pem -pubout -out auth-code-public.pem

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out encryption-private.pem
openssl pkey -in encryption-private.pem -pubout -out encryption-public.pem
```

{% hint style="danger" %}
Keep the four files in your secret manager and in your backups. The encryption pair cannot be replaced: with a new one, every stored credential is unreadable and each Employee connects again.
{% endhint %}

#### 8. Create the Secret

*Application team.* One Secret holds everything that is secret. Each key is the name of a setting, so the names must be exactly these.

```sh
kubectl -n mcp-gateway create secret generic mcp-gateway-secrets \
  --from-literal=CONNECTION_STRING='<from step 3>' \
  --from-literal=REDIS_CONNECTION_STRING='<from step 4>' \
  --from-literal=OPA_AUTH_TOKEN="$(openssl rand -hex 32)" \
  --from-literal=MCP_GATEWAY_API_API_KEY='<from Cakewalk>' \
  --from-literal=MCP_GATEWAY_API_API_SECRET='<from Cakewalk>' \
  --from-literal=IDP_MCP_DCR_PROXY_AGENTFORCE_SECRET='<from Cakewalk>' \
  --from-file=MCP_AUTH_CODE_PRIVATE_KEY=auth-code-private.pem \
  --from-file=MCP_AUTH_CODE_PUBLIC_KEY=auth-code-public.pem \
  --from-file=Encryption__PUBLIC_KMS_SERVICE_LOCAL_DEV_CERT=encryption-public.pem \
  --from-file=Encryption__DATA_KEY_UNWRAPPER_SERVICE_LOCAL_DEV_CERT=encryption-private.pem
```

If a tool of yours creates the Secret from a secret manager, keep the ten key names, and keep the line breaks of the four PEM values.

When PostgreSQL, Redis or your outbound proxy present a certificate of an internal authority, add that authority:

```sh
kubectl -n mcp-gateway create configmap corporate-ca --from-file=ca.crt=corporate-ca.crt
```

#### 9. Write the values

*Application team.* Save the values as `values.yaml` next to where you run `helm`, and keep the file in your Git repository: every upgrade uses it again. It holds no secret.

The first part is the same in both modes:

```yaml
gateway:
  publicUrl: https://mcp.example.com          # https, no path

# Only when you copied the images to your registry in step 2.
image:
  registry: registry.example.com/cakewalk
imagePullSecrets:
  - name: <your pull secret>

# Only when the cluster reaches the internet through a proxy.
proxy:
  httpsProxy: http://proxy.example.com:3128
  noProxy: .example.com,.svc,.cluster.local

# Only when you created the ConfigMap of step 8.
extraCaCertificates:
  configMapName: corporate-ca
```

Then add the `ingress` block of your mode.

{% tabs %}
{% tab title="Istio with the Gateway API" %}

```yaml
ingress:
  mode: gatewayApi
  host: mcp.example.com
  gatewayApi:
    gateway:
      name: shared-gateway
      namespace: istio-ingress
      sectionName: mcp-gateway        # the listener of step 5
```

The chart creates two resources: an `HTTPRoute` in the gateway's namespace, and an Istio `AuthorizationPolicy` in the namespace of your Gateway. The policy rejects a call to the configuration routes of this host from any address that is not Cakewalk's. It names this host only, so it does not touch the other applications of your Gateway.

When the application team may not create resources in the Gateway's namespace, add `createAuthorizationPolicy: false` under `gatewayApi`. The platform team then applies the policy itself, before step 10. Render it with:

```sh
helm template mcp-gateway <chart address> --version 1.1.0 -n mcp-gateway -f values.yaml \
  --set ingress.gatewayApi.createAuthorizationPolicy=true \
  --show-only templates/httproute.yaml
```

{% endtab %}

{% tab title="ingress-nginx" %}

```yaml
ingress:
  mode: nginx
  host: mcp.example.com
  className: nginx
  tlsSecretName: mcp-gateway-tls      # the Secret of step 5
```

The chart creates two `Ingress` resources for the host. One serves the Employee routes, with response buffering off and 10-minute timeouts. The other serves the configuration routes and allows Cakewalk's addresses only.
{% endtab %}
{% endtabs %}

The chart already allows Cakewalk's addresses on the configuration routes. Set `ingress.s2s.allowedSourceRanges` only when your ingress cannot see the original source address: then it holds the internal address of the firewall or load balancer that Cakewalk's calls come through.

{% hint style="info" %}
The chart runs one replica by default. With `replicaCount: 2` or more, an upgrade or the loss of a pod does not stop the gateway. The chart then adds a `PodDisruptionBudget` that keeps one replica running while nodes are drained, and it prefers a different node for each replica. That is a preference: when only one node has room, all replicas run on it. To require different nodes, set `topologySpreadConstraints` with `whenUnsatisfiable: DoNotSchedule`.

Check these before you set more than one replica:

* **The connection limit of PostgreSQL covers all replicas.** Each replica opens its own connections.
* \*\* Every replica uses the same PostgreSQL and the same Redis.
  {% endhint %}

When a pod stops, it keeps serving for 10 seconds (`preStopSleepSeconds`), so your ingress stops sending it requests first. That uses the sleep action of Kubernetes 1.30 or later: on an older cluster set `preStopSleepSeconds: 0`.

**Error reports (optional).** The gateway can send its errors to Sentry. It is off by default, and the gateway then sends nothing. You have three choices:

* **Leave it off.** Write nothing.
* **Send them to Cakewalk.** Ask Cakewalk for a DSN and an environment name. Cakewalk then sees the errors of your gateway and can help without asking you for logs.
* **Send them to your own Sentry.** Use the DSN of your project. Cakewalk does not see them, and it gives no support for that Sentry project.

```yaml
sentry:
  dsn: <the DSN>
  environment: <the name from Cakewalk, or a name of your own>
```

With a DSN, the gateway sends to that Sentry project:

* Its errors, each with the message and the stack trace of the exception, and the build of the image. When an upstream MCP server answers with an error, the message can hold text that the server sent.
* The ids of the company, of the user and of the request.
* The log lines that came before each error. They hold user ids and request query strings.
* A performance trace of one request in a thousand.

It never sends the body of an HTTP request. The gateway then needs outbound HTTPS to the host of the DSN, and it uses the proxy of your values when you set one.

#### 10. Install

*Application team.*

```sh
helm install mcp-gateway <chart address> --version 1.1.0 -n mcp-gateway -f values.yaml

kubectl -n mcp-gateway rollout status deployment/mcp-gateway
```

The first start creates the tables and can take a few minutes.

#### 11. Check

Both containers must be ready:

```sh
kubectl -n mcp-gateway get pods
# NAME                           READY   STATUS    RESTARTS
# mcp-gateway-6d9f7c5b8-x2x4k    2/2     Running   0
```

Then, from a machine of yours outside the cluster:

| Request                                                                    | Expected | Otherwise                                                                                        |
| -------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `curl -i https://mcp.example.com/.well-known/oauth-protected-resource/mcp` | 200      | 404: the route is not attached. 503: the pod is not ready, or a network rule blocks the ingress. |
| `curl -i https://mcp.example.com/api/v1/PublicKey`                         | 403      | 401: the request reached the gateway, so the address rule is missing.                            |
| `curl -i https://mcp.example.com/metrics`                                  | 404      |                                                                                                  |

#### 12. Tell Cakewalk

Until Cakewalk has set up your company on the gateway, the gateway rejects every Employee and has no Policies. During that time the policy engine's log repeats `Bundle load failed: server replied with Internal Server Error`. That is expected and stops when the company is set up.

After you tell us, our cloud reaches the gateway within minutes. The policy engine's log then shows the download of its policy bundle:

```sh
kubectl -n mcp-gateway logs deployment/mcp-gateway -c opa --tail=20
```

Then one Employee connects an Agent, adds a Connection and runs a tool. See [Employee Setup](https://www.cakewalk.security/docs/ai-agent-access/introduction/get-going-with-agent-access/employee-setup.md).

***

### 🧯 If something fails

```sh
kubectl -n mcp-gateway describe pod -l app.kubernetes.io/name=mcp-gateway
kubectl -n mcp-gateway logs deployment/mcp-gateway -c mcp-gateway --tail=100
kubectl -n mcp-gateway logs deployment/mcp-gateway -c opa --tail=100
```

| What you see                                                                                                                                             | Likely cause                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A TLS error on the gateway's host, before any HTTP answer                                                                                                | The certificate's Secret is missing, has another name, or is in the wrong namespace (step 5).                                                                                   |
| `ImagePullBackOff`                                                                                                                                       | The registry address in `image.registry`, a missing pull secret, or an image that was not copied.                                                                               |
| The gateway container restarts, and the log names a missing or invalid setting                                                                           | A key is missing in the Secret or has another name (step 8).                                                                                                                    |
| The gateway container restarts after about a minute, and the log ends with `Public Suffix List rule provider failed to build. Application cannot start.` | No outbound access to `publicsuffix.org`, or the proxy values are wrong.                                                                                                        |
| The gateway container restarts, and the log shows a database error                                                                                       | The connection string, a network rule, or a certificate that the gateway does not trust (the ConfigMap of step 8).                                                              |
| Cakewalk reports that it cannot reach the gateway                                                                                                        | Your perimeter does not allow Cakewalk's addresses.                                                                                                                             |
| Cakewalk reports that its calls answer 403                                                                                                               | Your ingress does not see Cakewalk's address as the source (step 5).                                                                                                            |
| Employees are rejected after Cakewalk has set up the company                                                                                             | The Employees belong to another Cakewalk company. The gateway accepts only yours.                                                                                               |
| The policy engine's log says `OPA is out of date`, or your firewall shows a call to `openpolicyagent.org`                                                | The policy engine checks for a newer version when it starts. It sends nothing of yours, and you can block the call. Do not replace the OPA image: Cakewalk chooses its version. |
| An Agent cannot register, `/dcr` answers 502                                                                                                             | The secret of the registration client is wrong (step 8), or the gateway cannot reach `idp2.getcakewalk.io`.                                                                     |

The logs go to standard output only. The gateway does not write tool-call payloads to them. They do hold user ids and request query strings, and the message of an error that an upstream MCP server answered can hold text of that server, so treat them as you treat access logs. When you ask Cakewalk for help, send the logs of both containers.

***

### 🔄 Upgrades and backups

* **Back up** the database, and keep the four key files of step 7. Back up the database before each upgrade.
* **Upgrade** when Cakewalk announces a version, to that chart version, with the same values:

  ```sh
  helm upgrade mcp-gateway <chart address> --version <new version> -n mcp-gateway -f values.yaml
  ```

  The new pod upgrades the tables as it starts, and an old pod is removed only when a new one is ready. An Agent with a call that is still running on an old pod 40 seconds after the pod starts to stop loses that call: it connects again, and the user repeats the call.
* **A rollback** returns to the older image and not to the older tables. After an upgrade that changed the tables, a rollback needs the database backup.
* **One supported version.** Cakewalk supports one version at a time, because its cloud changes continuously. Stay on the version that we announce. When we announce a new version, the previous one keeps working with Cakewalk's cloud for 15 days, so upgrade within that time. If you need more time, let us know.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.cakewalk.security/docs/ai-agent-access/on-premise-setup/deploy-on-kubernetes-with-helm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
