# Deployment Guide
This guide covers various deployment scenarios for the Kafka Schema Registry MCP Server v2.0.2 with **FastMCP 2.8.0+ framework**, **MCP 2025-06-18 specification compliance**, **Interactive Schema Migration**, and **Enhanced Security Features**, from local development to production environments.
## 🐳 Docker Deployment
### Quick Start with Pre-built Images (Recommended)
The fastest way to get started is using our pre-built DockerHub images:
```bash
# Option 1: Using Docker Compose (easiest)
git clone <repository-url>
cd kafka-schema-reg-mcp
docker-compose up -d
# Option 2: Direct Docker run with stable tag
docker run -p 38000:8000 aywengo/kafka-schema-reg-mcp:stable
# Option 3: With external Schema Registry
docker run -p 38000:8000 \
-e SCHEMA_REGISTRY_URL=http://your-schema-registry:8081 \
aywengo/kafka-schema-reg-mcp:stable
# Option 4: Multi-Registry Configuration
docker run -p 38000:8000 \
-e SCHEMA_REGISTRY_NAME_1=production \
-e SCHEMA_REGISTRY_URL_1=http://prod-registry:8081 \
-e SCHEMA_REGISTRY_NAME_2=staging \
-e SCHEMA_REGISTRY_URL_2=http://stage-registry:8081 \
aywengo/kafka-schema-reg-mcp:stable
```
**Available DockerHub Tags:**
- `aywengo/kafka-schema-reg-mcp:stable` - **Current stable release (v2.0.2) - Recommended**
- `aywengo/kafka-schema-reg-mcp:latest` - Latest build (may be pre-release)
- `aywengo/kafka-schema-reg-mcp:2.0.2` - Specific stable version
- `aywengo/kafka-schema-reg-mcp:2.0.1` - Previous stable version
- `aywengo/kafka-schema-reg-mcp:2.0.0` - FastMCP 2.8.0+ initial release
- **Multi-Platform Support**: Automatically detects `linux/amd64` or `linux/arm64`
> **💡 Recommendation**: Use `:stable` tag for production deployments to automatically receive stable updates.
### Local Development
For development or custom builds:
```bash
# Clone the repository
git clone <repository-url>
cd kafka-schema-reg-mcp
# Build and start all services
docker-compose up -d --build
# Verify deployment
curl http://localhost:38000/
```
**Services included:**
- **Kafka** (KRaft mode): `localhost:39092`
- **Schema Registry**: `localhost:38081`
- **MCP Server**: `localhost:38000`
- **AKHQ UI**: `localhost:38080`
### Production Docker Deployment
For production deployments, create a production-specific Docker Compose configuration:
```yaml
# docker-compose.prod.yml
version: '3.8'
services:
kafka:
image: confluentinc/cp-kafka:latest
environment:
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:29093
KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:29093
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 3
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 2
KAFKA_DEFAULT_REPLICATION_FACTOR: 3
KAFKA_MIN_INSYNC_REPLICAS: 2
KAFKA_AUTO_CREATE_TOPICS_ENABLE: false
volumes:
- kafka_data:/var/lib/kafka/data
deploy:
replicas: 3
resources:
limits:
memory: 2G
cpus: '1.0'
schema-registry:
image: confluentinc/cp-schema-registry:latest
environment:
SCHEMA_REGISTRY_HOST_NAME: schema-registry
SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: kafka:9092
SCHEMA_REGISTRY_LISTENERS: http://0.0.0.0:8081
SCHEMA_REGISTRY_KAFKASTORE_TOPIC_REPLICATION_FACTOR: 3
depends_on:
- kafka
deploy:
replicas: 2
mcp-server:
image: aywengo/kafka-schema-reg-mcp:stable
environment:
# Single Registry Configuration
SCHEMA_REGISTRY_URL: http://schema-registry:8081
SCHEMA_REGISTRY_USER: ${SCHEMA_REGISTRY_USER:-}
SCHEMA_REGISTRY_PASSWORD: ${SCHEMA_REGISTRY_PASSWORD:-}
# Multi-Registry Configuration (v1.5.0+)
SCHEMA_REGISTRY_NAME_1: "production"
SCHEMA_REGISTRY_URL_1: "http://schema-registry:8081"
SCHEMA_REGISTRY_USER_1: "${PROD_REGISTRY_USER}"
SCHEMA_REGISTRY_PASSWORD_1: "${PROD_REGISTRY_PASSWORD}"
VIEWONLY_1: "false"
SCHEMA_REGISTRY_NAME_2: "backup"
SCHEMA_REGISTRY_URL_2: "http://backup-registry:8081"
SCHEMA_REGISTRY_USER_2: "${BACKUP_REGISTRY_USER}"
SCHEMA_REGISTRY_PASSWORD_2: "${BACKUP_REGISTRY_PASSWORD}"
VIEWONLY_2: "true"
# Security Configuration (v2.0.x)
ENABLE_AUTH: "${ENABLE_AUTH:-false}"
AUTH_ISSUER_URL: "${AUTH_ISSUER_URL:-}"
AUTH_AUDIENCE: "${AUTH_AUDIENCE:-}"
# SSL/TLS Security Configuration (v2.0.0+)
ENFORCE_SSL_TLS_VERIFICATION: "${ENFORCE_SSL_TLS_VERIFICATION:-true}"
CUSTOM_CA_BUNDLE_PATH: "${CUSTOM_CA_BUNDLE_PATH:-}"
PYTHONUNBUFFERED: 1
ports:
- "38000:8000"
depends_on:
- schema-registry
deploy:
replicas: 2
resources:
limits:
memory: 1G
cpus: '1.0'
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/"]
volumes:
kafka_data:
driver: local
```
---
## ☸️ Kubernetes Deployment
### Namespace and ConfigMap
```yaml
# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: kafka-schema-registry
labels:
name: kafka-schema-registry
---
# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: mcp-server-config
namespace: kafka-schema-registry
data:
SCHEMA_REGISTRY_URL: "http://schema-registry-service:8081"
PYTHONUNBUFFERED: "1"
# Multi-Registry Configuration (v1.5.0+)
SCHEMA_REGISTRY_NAME_1: "default"
SCHEMA_REGISTRY_URL_1: "http://schema-registry-service:8081"
VIEWONLY_1: "false"
SCHEMA_REGISTRY_NAME_2: "backup"
SCHEMA_REGISTRY_URL_2: "http://backup-registry-service:8081"
VIEWONLY_2: "true"
# SSL/TLS Security Configuration (v2.0.0+)
ENFORCE_SSL_TLS_VERIFICATION: "true"
CUSTOM_CA_BUNDLE_PATH: ""
```
### MCP Server Deployment (v2.0.2)
```yaml
# k8s/mcp-server-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-server
namespace: kafka-schema-registry
labels:
app: mcp-server
version: "2.0.2"
spec:
replicas: 3
selector:
matchLabels:
app: mcp-server
template:
metadata:
labels:
app: mcp-server
version: "2.0.2"
spec:
containers:
- name: mcp-server
image: aywengo/kafka-schema-reg-mcp:stable
ports:
- containerPort: 8000
envFrom:
- configMapRef:
name: mcp-server-config
env:
# Backend Schema Registry Authentication
- name: SCHEMA_REGISTRY_USER
valueFrom:
secretKeyRef:
name: schema-registry-auth
key: username
optional: true
- name: SCHEMA_REGISTRY_PASSWORD
valueFrom:
secretKeyRef:
name: schema-registry-auth
key: password
optional: true
# MCP Server Authentication (v2.0.x)
- name: ENABLE_AUTH
valueFrom:
configMapRef:
name: mcp-server-config
key: ENABLE_AUTH
optional: true
- name: AUTH_ISSUER_URL
valueFrom:
secretKeyRef:
name: oauth-config
key: issuer-url
optional: true
- name: AUTH_AUDIENCE
valueFrom:
secretKeyRef:
name: oauth-config
key: audience
optional: true
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "1000m"
livenessProbe:
httpGet:
path: /
port: 8000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /
port: 8000
initialDelaySeconds: 10
periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
name: mcp-server-service
namespace: kafka-schema-registry
spec:
selector:
app: mcp-server
ports:
- name: http
port: 8000
targetPort: 8000
type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: mcp-server-ingress
namespace: kafka-schema-registry
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/rate-limit: "100"
spec:
tls:
- hosts:
- schema-mcp.your-domain.com
secretName: mcp-server-tls
rules:
- host: schema-mcp.your-domain.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: mcp-server-service
port:
number: 8000
```
---
## 🔧 Configuration Options
### Environment Variables (v2.0.2)
#### Core Configuration
| Variable | Description | Default | Since |
|----------|-------------|---------|-------|
| `SCHEMA_REGISTRY_URL` | Primary Schema Registry URL | `http://localhost:8081` | v1.0.0 |
| `SCHEMA_REGISTRY_USER` | Username for backend Schema Registry | *(empty)* | v1.0.0 |
| `SCHEMA_REGISTRY_PASSWORD` | Password for backend Schema Registry | *(empty)* | v1.0.0 |
| `VIEWONLY` | Enable view-only mode | `false` | v1.3.0 |
#### Multi-Registry Configuration (v1.5.0+)
| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `SCHEMA_REGISTRY_NAME_X` | Registry alias (X=1-8) | *(required)* | `production` |
| `SCHEMA_REGISTRY_URL_X` | Registry endpoint (X=1-8) | *(required)* | `http://prod-registry:8081` |
| `SCHEMA_REGISTRY_USER_X` | Username (X=1-8) | *(empty)* | `prod-user` |
| `SCHEMA_REGISTRY_PASSWORD_X` | Password (X=1-8) | *(empty)* | `prod-password` |
| `VIEWONLY_X` | Per-registry viewonly (X=1-8) | `false` | `true` |
#### Authentication & Authorization (v2.0.x)
| Variable | Description | Default | Applies To |
|----------|-------------|---------|------------|
| `ENABLE_AUTH` | Enable OAuth 2.1 authentication | `false` | MCP Server (frontend) |
| `AUTH_ISSUER_URL` | OAuth 2.1 issuer URL (automatic discovery) | *(empty)* | MCP Server (frontend) |
| `AUTH_AUDIENCE` | OAuth client ID or API identifier | *(empty)* | MCP Server (frontend) |
| `AUTH_VALID_SCOPES` | Comma-separated list of valid scopes | `read,write,admin` | MCP Server (frontend) |
| `AUTH_DEFAULT_SCOPES` | Comma-separated list of default scopes | `read` | MCP Server (frontend) |
| `AUTH_REQUIRED_SCOPES` | Comma-separated list of required scopes | `read` | MCP Server (frontend) |
### OAuth 2.1 Configuration Examples
#### Universal Provider Setup (v2.0.x)
```bash
# Enable OAuth 2.1 authentication
export ENABLE_AUTH=true
# Works with ANY OAuth 2.1 compliant provider
export AUTH_ISSUER_URL="https://your-oauth-provider.com"
export AUTH_AUDIENCE="your-client-id-or-api-identifier"
```
#### Provider-Specific Examples
**Azure AD:**
```bash
export AUTH_ISSUER_URL="https://login.microsoftonline.com/your-tenant-id/v2.0"
export AUTH_AUDIENCE="your-azure-client-id"
```
**Google OAuth 2.0:**
```bash
export AUTH_ISSUER_URL="https://accounts.google.com"
export AUTH_AUDIENCE="your-client-id.apps.googleusercontent.com"
```
**Keycloak:**
```bash
export AUTH_ISSUER_URL="https://your-keycloak-server.com/realms/your-realm"
export AUTH_AUDIENCE="your-keycloak-client-id"
```
### Multi-Registry Configuration Example
```bash
# Development Registry
export SCHEMA_REGISTRY_NAME_1="development"
export SCHEMA_REGISTRY_URL_1="http://dev-registry:8081"
export SCHEMA_REGISTRY_USER_1="dev-user"
export SCHEMA_REGISTRY_PASSWORD_1="dev-pass"
export VIEWONLY_1="false"
# Production Registry (with safety)
export SCHEMA_REGISTRY_NAME_2="production"
export SCHEMA_REGISTRY_URL_2="https://prod-registry:8081"
export SCHEMA_REGISTRY_USER_2="prod-user"
export SCHEMA_REGISTRY_PASSWORD_2="prod-pass"
export VIEWONLY_2="true" # Production safety
# Staging Registry
export SCHEMA_REGISTRY_NAME_3="staging"
export SCHEMA_REGISTRY_URL_3="https://staging-registry:8081"
export VIEWONLY_3="false"
```
---
## 📊 Resource Requirements
### Recommended Resources (v2.0.2)
| Component | CPU | Memory | Storage | Use Case |
|-----------|-----|--------|---------|----------|
| **MCP Server (Small)** | 0.5 | 512MB | - | <100 schemas, light usage |
| **MCP Server (Medium)** | 1.0 | 1GB | - | 100-1000 schemas, moderate operations |
| **MCP Server (Large)** | 2.0 | 2GB | 10GB | >1000 schemas, heavy migrations |
| **Schema Registry** | 0.5 | 1GB | 20GB | Per instance |
| **Kafka Broker** | 1.0 | 2GB | 100GB | Per broker, 3 minimum |
### Performance Considerations (v2.0.2)
The v2.0.2 release includes significant performance improvements:
- **Code Optimization**: 2,442 lines of redundant code removed
- **Memory Efficiency**: Enhanced resource management
- **Local Schema Validation**: Zero network dependencies for validation
- **Secure Logging**: No performance impact from credential masking
---
## 🔒 Security Considerations
### Production Security Checklist
- [ ] Enable authentication on Schema Registry (backend)
- [ ] Enable MCP Server authentication with `ENABLE_AUTH=true` (frontend)
- [ ] Use HTTPS/TLS for all connections
- [ ] Set `VIEWONLY=true` for production MCP instances
- [ ] Implement network policies in Kubernetes
- [ ] Use secrets management for credentials
- [ ] Enable audit logging
- [ ] Regular security scanning of images
- [ ] Implement rate limiting on ingress
### 🔑 Authentication Layers (v2.0.x)
**Two distinct authentication layers:**
1. **Schema Registry Authentication (Backend)**
- Controls how the MCP server connects to Kafka Schema Registry instances
- Set via `SCHEMA_REGISTRY_USER`, `SCHEMA_REGISTRY_PASSWORD`
- These credentials are NOT used to authenticate users of the MCP server
2. **MCP Server Authentication (Frontend)**
- Controls who can access the MCP server and its tools
- Enable with `ENABLE_AUTH=true` and configure OAuth 2.1 settings
- Optional - defaults to open access if not configured
### Security Features (v2.0.2)
- **🔒 Credential Protection**: Secure header management prevents credential exposure
- **📝 Secure Logging**: Automatic masking of authorization headers and sensitive data
- **🛡️ Safe Object Representations**: Credentials masked in `__repr__` and `__str__` methods
- **🔐 Dynamic Authentication**: Headers generated fresh on each access
### Example Network Policy
```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: mcp-server-netpol
namespace: kafka-schema-registry
spec:
podSelector:
matchLabels:
app: mcp-server
policyTypes:
- Ingress
- Egress
ingress:
- from:
- namespaceSelector:
matchLabels:
name: allowed-namespace
ports:
- protocol: TCP
port: 8000
egress:
- to:
- podSelector:
matchLabels:
app: schema-registry
ports:
- protocol: TCP
port: 8081
```
---
## 📈 Monitoring & Observability
### Health Checks
```bash
# Basic health check
curl http://localhost:38000/
# OAuth discovery endpoints (v2.0.x)
curl http://localhost:38000/.well-known/oauth-authorization-server
curl http://localhost:38000/.well-known/oauth-protected-resource
# Test MCP compliance (v2.0.x)
curl http://localhost:38000/mcp/compliance-status
```
### Docker Health Checks
```yaml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
---
## 🔄 Upgrade Guide
### Upgrading to v2.0.2
1. **Review Breaking Changes**: None between v2.0.1 and v2.0.2
2. **Update Image Tags**: Change to `aywengo/kafka-schema-reg-mcp:stable`
3. **Test New Features**: Interactive migration and enhanced security
4. **Verify Performance**: Check for improvements from code optimization
```bash
# Rolling update in Kubernetes
kubectl set image deployment/mcp-server \
mcp-server=aywengo/kafka-schema-reg-mcp:stable \
-n kafka-schema-registry
# Monitor rollout
kubectl rollout status deployment/mcp-server -n kafka-schema-registry
```
### Upgrading from v1.x to v2.x
See the comprehensive [v2.x Migration Guide](v2-migration-guide.md) for detailed instructions.
---
## 🤖 Claude Desktop Integration
### Docker-based Claude Desktop Configuration
```json
{
"mcpServers": {
"kafka-schema-registry": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--network", "host",
"-e", "SCHEMA_REGISTRY_URL",
"-e", "SCHEMA_REGISTRY_USER",
"-e", "SCHEMA_REGISTRY_PASSWORD",
"aywengo/kafka-schema-reg-mcp:stable"
],
"env": {
"SCHEMA_REGISTRY_URL": "http://localhost:8081",
"SCHEMA_REGISTRY_USER": "",
"SCHEMA_REGISTRY_PASSWORD": ""
}
}
}
}
```
### Multi-Registry Claude Desktop Configuration
```json
{
"mcpServers": {
"kafka-schema-registry": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--network", "host",
"-e", "SCHEMA_REGISTRY_NAME_1",
"-e", "SCHEMA_REGISTRY_URL_1",
"-e", "SCHEMA_REGISTRY_NAME_2",
"-e", "SCHEMA_REGISTRY_URL_2",
"aywengo/kafka-schema-reg-mcp:stable"
],
"env": {
"SCHEMA_REGISTRY_NAME_1": "development",
"SCHEMA_REGISTRY_URL_1": "http://localhost:8081",
"SCHEMA_REGISTRY_NAME_2": "production",
"SCHEMA_REGISTRY_URL_2": "https://prod-registry.company.com:8081"
}
}
}
}
```
### Testing Claude Desktop Integration
```bash
# Test Claude Desktop integration
"Test the connection to all Schema Registry instances"
"Show me the interactive migration features"
"List all available OAuth scopes and permissions"
```
---
## 🚀 CI/CD & Automated Publishing
### GitHub Actions Workflows
The project includes production-ready workflows:
- **Build Workflow**: Multi-platform builds with security scanning
- **Publish Workflow**: Automated DockerHub publishing on version tags
- **Multi-Platform Support**: AMD64 + ARM64 architectures
- **Security Scanning**: Trivy vulnerability analysis
### Setting Up CI/CD
1. **Configure DockerHub Secrets**:
```bash
DOCKERHUB_USERNAME=your-username
DOCKERHUB_TOKEN=your-access-token
```
2. **Create Version Tag**:
```bash
git tag v2.0.3
git push origin v2.0.3
```
3. **Automated Process**: GitHub Actions handles building, testing, and publishing
---
This deployment guide provides comprehensive instructions for deploying the Kafka Schema Registry MCP Server v2.0.2 with FastMCP 2.8.0+ framework, enhanced security features, and interactive migration capabilities across various production environments.
