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

// integration

Connect an MCP server

Applies to

Product: Cloud · Server · Audience: Developer / Integrator · Platform Operator · Administrator

Registering an MCP server with basebox – for the shipped connectors via the admin interface, for your own servers on basebox Server via Helm – and making it available to apps. The connection always has two halves: deployment (the service runs and is reachable) and enablement (an administrator activates it for the organisation and apps).

Three paths

Path For Who
Shipped connector Calculator, web search, e-mail, DokuWiki, Nextcloud, Atlassian Platform Operator enables the workload via Helm (Server) or basebox (Cloud); administrator configures and enables
Hosted MCP server Services the provider itself offers as MCP – e.g. YouTrack via the JetBrains integration No in-cluster workload needed; administrator configures endpoint and enables
Your own MCP server (BYO) Your self-built connector Platform Operator deploys it via Helm (Server); in the Cloud in coordination with basebox

Path 1: enable a shipped connector

On basebox Server, the Platform Operator creates a values file that switches on the desired connectors and sets external endpoints:

global:
  email:
    imapHost: imap.example.com
    imapPort: "993"
    imapConnectionType: tls
  dokuwiki:
    rpcUrl: https://wiki.example.com/lib/exe/xmlrpc.php

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

and applies it together with the installation values (helm upgrade --install … --values values.customer.yaml --values values.mcp.yaml). Every enabled connector gets a deployment and a ClusterIP service. The full guide including web search egress: Deploying MCP connectors with Helm.

Afterwards the administrator completes the setup: Administration → Connectors → open the connector → fields (base URL, possibly service account or API key) → Test connection → switch on → enable in the desired apps. See Configuring connectors.

Path 2: deploy your own MCP server

Add your server under mcp.mcps with tier byo:

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 service mcp-internal-tools; if your server uses the default path /mcp, its in-cluster endpoint is http://mcp-internal-tools:8000/mcp.

Machine credentials (e.g. a token with which the server addresses an internal system for everyone) are referenced as a Kubernetes secret instead of being written into the values:

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

Personal credentials per user do not belong in the deployment: users store them in basebox, and basebox passes them to your server per request in the Authorization header.

Verify the deployment:

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

The server then appears in Administration → Connectors (possibly as "Registered via CLI") and is configured and enabled like any other connector.

Requirements for your own server

  • HTTP transport on the configured port, endpoint /mcp (or as specified in the chart).
  • Non-root container that meets the chart's security defaults, with readiness and liveness probes.
  • Header pass-through: pass the Authorization header on to the target system unchanged when users use personal credentials. No caching of credentials or results across users.
  • Network: the server reaches only its target system. Network policy, DNS, TLS trust and firewall must allow exactly this path; the MCP gateway blocks everything else.
  • Tool design: clear names and descriptions, bounded and structured results, write tools separate from read tools – see Build connectors.

In basebox Cloud

The shipped connectors are provided by basebox; you configure and enable them as administrator. Your own MCP server or an externally hosted endpoint is connected by basebox in coordination with you – contact support@basebox.ai. Note that the Cloud has to reach your target system from the Noris data center – see Network connectivity.

Checklist before enabling

  • Deployment and service are running; probes are green
  • Test connection in the administration succeeds
  • Authentication model decided and documented – personal credentials or service account (Connector authentication)
  • Write tools decided deliberately (off by default)
  • Connector enabled only in the apps that need it – web search in a dedicated app
  • Users know how to generate a token and enter it under "+"

Next: MCP client · Build connectors · Deploying MCP connectors with Helm