Ctrlk
Log inSign up

Deploy Natoma On-Prem (Helm)

Deploy the Natoma on-premises agent using a Helm chart on Kubernetes, connecting to your self-hosted MCP servers.

This guide covers deploying the Natoma agent on-premises using a Helm chart. The on-prem agent connects to the Natoma cloud control plane for orchestration while routing all MCP traffic within your own infrastructure.

Prerequisites

  • A running Kubernetes cluster with Helm installed

  • Access to the Natoma tenant admin panel with Admin permissions

  • Network access to Docker Hub (or your internal registry) to pull the Natoma agent image

Network Requirements

You may need to allowlist both inbound and outbound traffic depending on your network configuration.

Type
IP Address
Notes

Natoma egress

35.247.116.223

May not be utilized for on-prem since traffic will always be unidirectional from agent to Natoma.

Natoma ingress

34.49.218.52

Agents will make calls to the Natoma API and auth server.

Agent Image & Helm Chart

Natoma agent images are hosted on Docker Hub and AWS ECR. Pull commands for Docker Hub are shown below. Contact the Natoma team for ECR access or alternative registry details.

If your Kubernetes cluster cannot reach Docker Hub directly, host the agent image in an internal registry and point image.repository at your internal path.

# Authenticate into Docker using the token provided by Natoma
echo "dkcr_oat_xxxxx" | docker login registry-1.docker.io \
  -u natomalabs --password-stdin

# Pull the Natoma agent image (confirm the latest version with the Natoma team)
docker pull natomalabs/agent:0.0.8

Setup

Step 1: Retrieve On-Prem Credentials

  1. In your Natoma tenant admin panel, navigate to Admin Settings.

  2. Create a new set of on-premise credentials.

  3. Copy the Client ID and Client Secret — you will need both when configuring the Helm chart.

Store the Client ID and Client Secret securely. You will reference these values in your Helm configuration.

Step 2: Create an On-Prem MCP Server

  1. In the Natoma web app, navigate to Apps.

  2. Add a new custom app and set the Source Type to Remote URL.

  3. Check the option This is an on-prem server.

  4. Enter the remote URL pointing to your on-prem MCP server, appending the /mcp suffix to the URL.

Step 3: Configure and Deploy the Helm Chart

See the Helm Configuration reference below for full details on all supported values. At minimum, supply the required parameters at install time.

Step 4: Verify Tool Scanning

Once the agent is deployed and running, Natoma automatically detects it and initiates tool scanning. Each time the on-prem agent polls the Natoma cloud server, any pending scan requests are processed alongside the polling data — no additional configuration is required.

Helm Configuration

Required Values

The following properties must be provided at install time for the agent to connect to Natoma's cloud services and serve MCP traffic.

natoma.clientID

The Client ID generated within the Natoma web application for this clustered deployment.

natoma.clientSecret.*

Contains secretName and secretKey properties pointing to the Kubernetes secret that holds the Natoma client secret. The defaults expect a secret named natoma with a client-secret key.

Create the secret with:

ingress.host

The hostname through which MCP traffic will be routed. This must be routable and resolvable by all end-users who will connect to MCP servers through the Natoma agent.

image.repository

Full image name including the repository path. If using the Natoma-hosted image, contact the Natoma team for guidance.

image.tag

A specific version tag for the agent image. This value will differ if you are self-hosting the image.

Optional Values

The following properties can be configured for more flexible or complex deployments. For help, reach out to the Natoma team or email [email protected].

replicaCount

Configured number of replicas for the agent service. Ignored when autoscaling.enabled: true.

Default: 2

autoscaling.enabled

Set to true to configure and enable horizontal pod autoscaling.

Default: false

autoscaling.minReplicas

Minimum number of service replicas available during periods of low activity.

Default: 1

autoscaling.maxReplicas

Maximum number of service replicas available for scaling.

Default: 8

autoscaling.targetCPUUtilizationPercentage

CPU utilization percentage to target for horizontal scaling.

Default: 80

natoma.logLevel

Supported values: debug, info, warn, error. Leave at info during production use unless advised otherwise by Natoma support for troubleshooting.

Default: info

natoma.extraCACerts.*

Enables the Natoma agent process to validate certificates from MCP servers that rely on an internal root CA. Configure the root certificates in a Kubernetes ConfigMap containing a single PEM-formatted file.

Create the ConfigMap with:

Set natoma.extraCACerts.configMap to extra-certs and natoma.extraCACerts.key to internal-ca.pem.

ingress.enabled

Set to false to disable the default Ingress resource. This may be necessary for complex networking environments or certain managed Kubernetes providers.

Default: true

ingress.tls.secretName

Name of a Kubernetes Secret containing a crt key (full certificate chain) and a key key (certificate private key).

Create the secret with:

Set ingress.tls.secretName to example-tls.

ingress.tls.hosts

When TLS is required, a string array of hostnames matching the certificate's CN and any DNS Alternative Names. Specify using {} notation via the Helm CLI:

ingress.annotations.*

Optional annotations to configure on the Ingress resource. May be necessary to control behavior within managed Kubernetes providers. Escape . characters when passing via the Helm CLI:

Sample values.yaml

Support

Please reach out to the Natoma team or email [email protected].

Last updated