Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

Deploy MCP Connectors with Helm

basebox uses the Model Context Protocol (MCP) to connect the assistant to tools and external systems. The basebox.ai Helm chart can run MCP servers inside the Kubernetes cluster as dedicated Deployments and ClusterIP Services.

MCP workloads are opt-in. Each connector is enabled explicitly for the target installation, so you can deploy only the services that belong in that environment.

Deployment Model

Enabling a connector in Helm creates its Kubernetes workload and internal Service. An administrator then configures and enables the connector in basebox. This separates platform deployment from application-level access.

The chart includes definitions for these connectors:

Connector Helm key Installation setting
Calculator calculator No external service required
Web search ddg Outbound HTTPS access
Email email-rs IMAP host, port, and connection type
DokuWiki doku-rs DokuWiki XML-RPC URL
Nextcloud nextcloud Nextcloud base URL
Atlassian atlassian Jira and/or Confluence base URL

Calculator, Web search, and Email form the standard connected installation profile. DokuWiki, Nextcloud, and Atlassian are available for project-specific integrations coordinated with Basebox support.

YouTrack uses the hosted JetBrains MCP integration and does not require an in-cluster Helm workload.

Enable the Connected Profile

Create values.mcp.yaml:

global:
  email:
    imapHost: imap.example.com
    imapPort: "993"
    imapConnectionType: tls

mcp:
  mcps:
    calculator:
      enabled: true
    ddg:
      enabled: true
    email-rs:
      enabled: true

Replace the IMAP hostname with the service used by your organization. Mailbox credentials are entered by users in basebox and do not belong in this file.

Apply the MCP values together with the installation-specific values:

helm upgrade --install basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.29 \
  --namespace basebox \
  --create-namespace \
  --wait \
  --timeout 120m \
  --values values.customer.yaml \
  --values values.mcp.yaml

Configure External Systems

Set external endpoints in the installation values before enabling the matching connector:

global:
  dokuwiki:
    rpcUrl: https://wiki.example.com/lib/exe/xmlrpc.php
  nextcloud:
    host: https://cloud.example.com
  atlassian:
    jiraUrl: https://jira.example.com
    confluenceUrl: https://confluence.example.com

mcp:
  mcps:
    doku-rs:
      enabled: true
    nextcloud:
      enabled: true
    atlassian:
      enabled: true

Enable only the connectors used by the installation. Network policy, DNS, TLS trust, and firewall rules must allow the MCP workload to reach its configured external system.

Deploy a Custom MCP Server

Add a custom server under mcp.mcps with the byo tier. The example below deploys an internal MCP image that listens on port 8000:

mcp:
  mcps:
    internal-tools:
      enabled: true
      tier: byo
      image: registry.example.com/basebox/internal-tools
      tag: v1.0.0
      port: 8000
      env:
        MCP_HOST: 0.0.0.0
        MCP_PORT: "8000"
      readinessProbe:
        tcpSocket:
          port: http
        periodSeconds: 10
      livenessProbe:
        tcpSocket:
          port: http
        periodSeconds: 30

The chart creates the internal Service mcp-internal-tools. If the server uses the standard /mcp path, its in-cluster endpoint is:

http://mcp-internal-tools:8000/mcp

The custom image should support the chart's non-root security defaults and the configured MCP transport.

For a Kubernetes-managed machine credential, reference an existing Secret instead of putting the value directly in Helm values:

mcp:
  mcps:
    internal-tools:
      env:
        API_TOKEN:
          valueFrom:
            secretKeyRef:
              name: internal-tools-credentials
              key: api-token

User-specific connector credentials are configured through basebox, where they remain associated with the individual user.

Verify the Deployment

List the enabled MCP workloads and their internal endpoints:

kubectl -n basebox get deployments,services,endpoints \
  -l app.kubernetes.io/instance=basebox,app.kubernetes.io/component=mcp

Each enabled connector has one Deployment and one Service. Complete the setup under Administration > Connectors, test the connection, and then enable it for the organization.

See MCP Connectors for connector-specific setup and Connectors for the administrator workflow.