ToolHive MCP Server Secure Containerized Deployment

Overview

ToolHive’s MCP (Model Context Protocol) server is a lightweight, container-first service that centralizes model context and tool integrations for applications that use large language models. Packaged for container runtimes, the server aims to make local development, CI environments, and production deployments consistent and easy to manage while enforcing basic security controls (TLS, token-based auth, secrets).

This document explains how to deploy the MCP server in containers, how to configure it, and practical usage patterns. It assumes a developer audience familiar with Docker/Kubernetes and basic security practices, and focuses on concrete commands and examples for safe, repeatable deployments.

Features

• Containerized single-binary server for easy distribution and updates
• Configurable via environment variables and mounted config files
• TLS support for encrypted transport
• Token-based admin/auth mechanism for simple access control
• Persistent storage options via mounted volumes
• Health and basic metrics endpoints for observability
• Small footprint, intended for local dev, CI, and edge deployments

Installation / Configuration

The MCP server can be built from source or run via a prebuilt image (see the repo for an official image). Below are common deployment patterns.

Build locally (if you need to build from the repository):

git clone https://github.com/StacklokLabs/toolhive.git
cd toolhive
docker build -t toolhive/mcp:local .

Run with Docker (development / quick test):

docker run -d \
  --name toolhive-mcp \
  -p 127.0.0.1:8080:8080 \
  -e MCP_ADMIN_TOKEN="replace-with-secure-token" \
  -e MCP_PORT=8080 \
  -v /path/to/data:/var/lib/toolhive \
  -v /path/to/certs:/etc/toolhive/certs:ro \
  toolhive/mcp:local

Docker Compose example:

version: "3.8"
services:
  mcp:
    image: toolhive/mcp:local
    ports:
      - "8080:8080"
    environment:
      MCP_ADMIN_TOKEN: "${MCP_ADMIN_TOKEN}"
      MCP_PORT: "8080"
    volumes:
      - ./data:/var/lib/toolhive
      - ./certs:/etc/toolhive/certs:ro
    restart: unless-stopped

Kubernetes deployment (example):

apiVersion: v1
kind: Secret
metadata:
  name: toolhive-secrets
type: Opaque
data:
  admin-token: BASE64_ENCODED_TOKEN
  tls.crt: BASE64_ENCODED_CERT
  tls.key: BASE64_ENCODED_KEY
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: toolhive-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: toolhive-mcp
  template:
    metadata:
      labels:
        app: toolhive-mcp
    spec:
      containers:
        - name: mcp
          image: toolhive/mcp:latest
          env:
            - name: MCP_ADMIN_TOKEN
              valueFrom:
                secretKeyRef:
                  name: toolhive-secrets
                  key: admin-token
            - name: MCP_PORT
              value: "8080"
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: tls
              mountPath: /etc/toolhive/certs
              readOnly: true
      volumes:
        - name: tls
          secret:
            secretName: toolhive-secrets
            items:
              - key: tls.crt
                path: tls.crt
              - key: tls.key
                path: tls.key
---
apiVersion: v1
kind: Service
metadata:
  name: toolhive-mcp
spec:
  selector:
    app: toolhive-mcp
  ports:
    - port: 8080
      targetPort: 8080
      protocol: TCP

Typical configuration file (optional, YAML):

server:
  host: 0.0.0.0
  port: 8080
security:
  tls:
    certFile: /etc/toolhive/certs/tls.crt
    keyFile: /etc/toolhive/certs/tls.key
  adminTokenEnv: MCP_ADMIN_TOKEN
storage:
  dataDir: /var/lib/toolhive
logging:
  level: info

Common environment variables