Documentation on Cloud Native MCP Server

Architecture Guide

Mon, 01 Jan 0001 00:00:00 +0000

Architecture Guide#

This document describes the system architecture and design principles of Cloud Native MCP Server.

Table of Contents#

Overview
System Architecture
Core Components
Service Integration
Data Flow
Design Principles
Performance Optimization
Scalability

Overview#

Cloud Native MCP Server is a high-performance Model Context Protocol (MCP) server for managing Kubernetes and cloud-native infrastructure. It adopts a modular design with support for multiple runtime modes and protocols.

Architecture Goals#

High Performance: Optimized caching, connection pooling, and resource management
Scalability: Modular design, easy to add new services
Security: Multi-layer authentication, input sanitization, and audit logging
Observability: Built-in metrics, logging, and tracing
Reliability: Health checks, retry mechanisms, and graceful degradation

System Architecture#

┌─────────────────────────────────────────────────────────────┐
│ Client │
│ (Claude Desktop, Browser, Custom MCP Clients) │
└────────────────────┬────────────────────────────────────────┘
 │
 │ MCP Protocol (SSE/Streamable-HTTP)
 │
┌────────────────────▼────────────────────────────────────────┐
│ HTTP Server │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Routing Layer (SSE/Streamable-HTTP) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Middleware Layer │ │
│ │ - Authentication (API Key/Bearer/Basic) │ │
│ │ - Audit Logging │ │
│ │ - Rate Limiting │ │
│ │ - Security Middleware │ │
│ │ - Metrics Collection │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ Service Management Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Kubernetes│ │ Helm │ │ Grafana │ │Prometheus│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Kibana │ │Elastic │ │ AlertMgr │ │ Jaeger │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Otel │ │Utilities │ │
│ └──────────┘ └──────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ Infrastructure Layer │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Cache Layer (LRU/Segmented) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Secret Management │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Logging System │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Metrics System │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ External Services │
│ Kubernetes Cluster, Grafana, Prometheus, ES, etc. │
└─────────────────────────────────────────────────────────────┘

Core Components#

1. HTTP Server#

Responsibility: Handle incoming HTTP/SSE requests and connections

Configuration Guide

Mon, 01 Jan 0001 00:00:00 +0000

Configuration Guide#

This guide covers all configuration options for Cloud Native MCP Server.

Configuration Methods#

K8s MCP Server supports three configuration methods (in order of priority):

Command Line Arguments - Highest priority
Environment Variables - Medium priority
YAML Configuration File - Lowest priority

Configuration Priority Example#

1
2
3
4
5
6
7


# Configuration file sets default values
# Environment variables override configuration file
# Command line arguments override all settings

./cloud-native-mcp-server \
 --config=config.yaml \
 --log-level=debug

Server Configuration#

Basic Settings#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


server:
 # Run mode: sse | streamable-http
 # Recommended: streamable-http for production, sse for broad compatibility
 mode: "sse"

 # Server listen address
 addr: "0.0.0.0:8080"

 # HTTP read timeout (seconds)
 # 0 = no timeout (not recommended for production)
 # Recommended: 30-60 seconds
 readTimeoutSec: 30

 # HTTP write timeout (seconds)
 # Should be set to 0 for SSE connections to keep them alive
 writeTimeoutSec: 0

 # HTTP idle timeout (seconds)
 # Default: 60 seconds
 idleTimeoutSec: 60

SSE Path Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


server:
 ssePaths:
 # Kubernetes SSE endpoint
 kubernetes: "/api/kubernetes/sse"

 # Grafana SSE endpoint
 grafana: "/api/grafana/sse"

 # Prometheus SSE endpoint
 prometheus: "/api/prometheus/sse"

 # Kibana SSE endpoint
 kibana: "/api/kibana/sse"

 # Helm SSE endpoint
 helm: "/api/helm/sse"

 # Alertmanager SSE endpoint
 alertmanager: "/api/alertmanager/sse"

 # Elasticsearch SSE endpoint
 elasticsearch: "/api/elasticsearch/sse"

 # OpenTelemetry SSE endpoint
 opentelemetry: "/api/opentelemetry/sse"

 # Utilities SSE endpoint
 utilities: "/api/utilities/sse"

 # Aggregated SSE endpoint for all services
 aggregate: "/api/aggregate/sse"

Streamable-HTTP Path Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


server:
 streamableHttpPaths:
 # Kubernetes Streamable-HTTP endpoint
 kubernetes: "/api/kubernetes/streamable-http"

 # Grafana Streamable-HTTP endpoint
 grafana: "/api/grafana/streamable-http"

 # Prometheus Streamable-HTTP endpoint
 prometheus: "/api/prometheus/streamable-http"

 # Kibana Streamable-HTTP endpoint
 kibana: "/api/kibana/streamable-http"

 # Helm Streamable-HTTP endpoint
 helm: "/api/helm/streamable-http"

 # Alertmanager Streamable-HTTP endpoint
 alertmanager: "/api/alertmanager/streamable-http"

 # Elasticsearch Streamable-HTTP endpoint
 elasticsearch: "/api/elasticsearch/streamable-http"

 # OpenTelemetry Streamable-HTTP endpoint
 opentelemetry: "/api/opentelemetry/streamable-http"

 # Utilities Streamable-HTTP endpoint
 utilities: "/api/utilities/streamable-http"

 # Aggregated Streamable-HTTP endpoint for all services
 aggregate: "/api/aggregate/streamable-http"

Command Line Arguments#

Parameter	Description	Default
`--mode`	Server mode (sse, streamable-http)	sse
`--addr`	Listen address	0.0.0.0:8080
`--config`	Configuration file path	config.yaml
`--log-level`	Log level (debug, info, warn, error)	info

Environment Variables#

Variable	Description	Default
`MCP_MODE`	Server mode	sse
`MCP_ADDR`	Listen address	0.0.0.0:8080
`MCP_LOG_LEVEL`	Log level	info

Service Configuration#

Kubernetes#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


kubernetes:
 # kubeconfig file path
 # If empty, uses default: $KUBECONFIG → ~/.kube/config → service account
 kubeconfig: ""

 # Timeout for a single API call (seconds)
 timeoutSec: 30

 # API client queries per second (QPS)
 qps: 100.0

 # API client burst rate
 burst: 200

Prometheus#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


prometheus:
 # Enable/disable Prometheus service
 enabled: false

 # Prometheus server address
 # Format: http://host:port or https://host:port
 address: "http://localhost:9090"

 # Request timeout (seconds)
 timeoutSec: 30

 # Basic auth username (optional)
 username: ""

 # Basic auth password (optional)
 password: ""

 # Bearer token authentication (optional, higher priority than Basic Auth)
 bearerToken: ""

 # Skip TLS certificate verification
 # Do not use in production!
 tlsSkipVerify: false

 # TLS client certificate file path (for mTLS authentication)
 tlsCertFile: ""

 # TLS client key file path
 tlsKeyFile: ""

 # TLS CA certificate file path
 tlsCAFile: ""

Grafana#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


grafana:
 # Enable/disable Grafana service
 enabled: false

 # Grafana server URL
 # Format: http://host:port or https://host:port
 url: "http://localhost:3000"

 # Grafana API Key (recommended)
 # Create in Grafana: Administration → API Keys
 apiKey: ""

 # Basic auth username (alternative to API Key)
 username: ""

 # Basic auth password
 password: ""

 # Request timeout (seconds)
 timeoutSec: 30

Kibana#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


kibana:
 # Enable/disable Kibana service
 enabled: false

 # Kibana server URL
 # Format: http://host:port or https://host:port
 url: "https://localhost:5601"

 # Kibana API Key (recommended)
 # Create in Kibana: Stack Management → API Keys
 apiKey: ""

 # Basic auth username (alternative to API Key)
 username: ""

 # Basic auth password
 password: ""

 # Request timeout (seconds)
 timeoutSec: 30

 # Skip TLS certificate verification
 # Do not use in production!
 skipVerify: false

 # Kibana space name
 # Default: "default"
 space: "default"

Helm#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


helm:
 # Enable/disable Helm service
 enabled: false

 # Helm operations kubeconfig path
 # If empty, uses the same kubeconfig as Kubernetes client
 kubeconfigPath: ""

 # Default namespace for Helm operations
 namespace: "default"

 # Enable Helm debug mode
 debug: false

 # Repository update timeout (seconds)
 # Default: 300 (5 minutes)
 # Recommended for China: 600-900
 timeoutSec: 300

 # Maximum retry attempts
 # Number of retries for failed repository updates
 # Default: 3
 # Recommended: 3-5
 maxRetries: 3

 # Enable mirrors
 # Used to accelerate Helm repository pulls
 # Default: false
 useMirrors: false

 # Custom mirror mapping
 # Format: original repository URL -> mirror URL
 mirrors: {}

Elasticsearch#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


elasticsearch:
 # Enable/disable Elasticsearch service
 enabled: false

 # Elasticsearch server addresses (supports multi-node HA)
 addresses:
 - "http://localhost:9200"

 # Single Elasticsearch server address (alternative to addresses)
 # Used when addresses is empty
 address: ""

 # Basic auth username
 username: ""

 # Basic auth password
 password: ""

 # Bearer token authentication (optional, higher priority than Basic Auth)
 bearerToken: ""

 # API Key authentication (optional, highest priority)
 # Format: id:api_key
 apiKey: ""

 # Request timeout (seconds)
 timeoutSec: 30

 # Skip TLS certificate verification
 # Do not use in production!
 tlsSkipVerify: false

 # TLS client certificate file path (for mTLS authentication)
 tlsCertFile: ""

 # TLS client key file path
 tlsKeyFile: ""

 # TLS CA certificate file path
 tlsCAFile: ""

Alertmanager#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


alertmanager:
 # Enable/disable Alertmanager service
 enabled: false

 # Alertmanager server address
 # Format: http://host:port or https://host:port
 address: "http://localhost:9093"

 # Request timeout (seconds)
 timeoutSec: 30

 # Basic auth username (optional)
 username: ""

 # Basic auth password (optional)
 password: ""

 # Bearer token authentication (optional, higher priority than Basic Auth)
 bearerToken: ""

 # Skip TLS certificate verification
 # Do not use in production!
 tlsSkipVerify: false

 # TLS client certificate file path (for mTLS authentication)
 tlsCertFile: ""

 # TLS client key file path
 tlsKeyFile: ""

 # TLS CA certificate file path
 tlsCAFile: ""

OpenTelemetry#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


opentelemetry:
 # Enable/disable OpenTelemetry service
 enabled: false

 # OpenTelemetry Collector address
 # Format: http://host:port or https://host:port
 address: "http://localhost:4318"

 # Request timeout (seconds)
 timeoutSec: 30

 # Basic auth username (optional)
 username: ""

 # Basic auth password (optional)
 password: ""

 # Bearer token authentication (optional, higher priority than Basic Auth)
 bearerToken: ""

 # Skip TLS certificate verification
 # Do not use in production!
 tlsSkipVerify: false

 # TLS client certificate file path (for mTLS authentication)
 tlsCertFile: ""

 # TLS client key file path
 tlsKeyFile: ""

 # TLS CA certificate file path
 tlsCAFile: ""

Utilities#

1
2
3


utilities:
 # Utilities service is always enabled
 enabled: true

Authentication Configuration#

API Key Authentication#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


auth:
 # Enable/disable authentication
 enabled: false

 # Authentication mode: apikey | bearer | basic
 # apikey: X-API-Key simple API key authentication
 # bearer: Bearer Token (JWT) authentication
 # basic: HTTP Basic Auth
 mode: "apikey"

 # API Key (for apikey mode)
 # Minimum 8 characters, recommended 16+ characters
 apiKey: ""

 # Bearer token (for bearer mode)
 # Minimum 16 characters recommended (JWT token)
 bearerToken: ""

 # Basic Auth username
 username: ""

 # Basic Auth password
 password: ""

 # JWT secret (for JWT verification)
 jwtSecret: ""

 # JWT algorithm (HS256, RS256, etc.)
 jwtAlgorithm: "HS256"

Authentication Environment Variables#

Variable	Description
`MCP_AUTH_ENABLED`	Enable authentication (1, true, yes, on)
`MCP_AUTH_MODE`	Authentication mode (apikey, bearer, basic)
`MCP_AUTH_API_KEY`	API key or bearer token
`MCP_AUTH_USERNAME`	Basic auth username
`MCP_AUTH_PASSWORD`	Basic auth password
`MCP_AUTH_JWT_SECRET`	JWT secret
`MCP_AUTH_JWT_ALGORITHM`	JWT algorithm

Logging Configuration#

1
2
3
4
5
6
7


logging:
 # Log level: debug | info | warn | error
 level: "info"

 # Use JSON format logs
 # Suitable for log aggregation systems (ELK, Splunk, etc.)
 json: false

Log Level Description#

debug: Detailed debugging information, including all requests and responses
info: General information, including important operations and status changes
warn: Warning information, does not affect functionality but needs attention
error: Error information, functionality is impaired

Audit Logs#

Basic Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


audit:
 # Enable/disable audit logging
 enabled: false

 # Audit log level: debug | info | warn | error
 level: "info"

 # Audit log storage: stdout | file | database | all
 storage: "memory"

 # Log format: text | json
 # json: Structured JSON format, suitable for log aggregation
 # text: Human-readable text format
 format: "json"

 # Maximum query results
 maxResults: 1000

 # Query time range (days)
 timeRange: 90

File Storage Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


audit:
 storage: "file"
 file:
 # Log file path
 path: "/var/log/cloud-native-mcp-server/audit.log"

 # Maximum log file size (MB)
 maxSizeMB: 100

 # Maximum number of backup files
 maxBackups: 10

 # Maximum log file age (days)
 maxAgeDays: 30

 # Compress rotated log files
 compress: true

 # Maximum number of logs in memory storage
 maxLogs: 10000

Database Storage Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


audit:
 storage: "database"
 database:
 # Database type: sqlite | postgresql | mysql
 type: "sqlite"

 # SQLite database file path
 # Used only when type="sqlite"
 sqlitePath: "/var/lib/cloud-native-mcp-server/audit.db"

 # PostgreSQL connection string
 # Used only when type="postgresql"
 # Format: postgresql://user:password@host:port/dbname
 connectionString: ""

 # Database table name
 tableName: "audit_logs"

 # Maximum number of records
 maxRecords: 100000

 # Cleanup interval (hours)
 cleanupInterval: 24

Query API Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


audit:
 query:
 # Enable query API
 enabled: true

 # Maximum results per query
 maxResults: 1000

 # Maximum time range (days)
 timeRange: 90

Sensitive Data Masking Configuration#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


audit:
 masking:
 # Enable masking
 enabled: true

 # Fields to mask
 fields:
 - password
 - token
 - apiKey
 - secret
 - passwd
 - pwd
 - authorization

 # Mask replacement value
 maskValue: "***REDACTED***"

Sampling Configuration (High Traffic Scenarios)#

1
2
3
4
5
6
7
8


audit:
 sampling:
 # Enable sampling
 enabled: false

 # Sampling rate (0-1)
 # 1.0 = log all, 0.1 = log 10%
 rate: 1.0

Service and Tool Filtering#

1
2
3
4
5
6
7
8
9


enableDisable:
 # Disabled services (comma-separated)
 disabledServices: []

 # Enabled services (comma-separated, overrides disabled list)
 enabledServices: []

 # Disabled tools (comma-separated)
 disabledTools: []

Performance Tuning#

Use currently supported tuning knobs:

Deployment Guide

Mon, 01 Jan 0001 00:00:00 +0000

Deployment Guide#

This guide covers various deployment strategies and best practices for Cloud Native MCP Server.

Table of Contents#

Prerequisites
Quick Deployment
Kubernetes Deployment
Docker Deployment
Helm Deployment
Production Considerations
Monitoring and Observability
Security Best Practices
Troubleshooting

Prerequisites#

System Requirements#

Operating System: Linux, macOS, or Windows
CPU: Minimum 1 core, recommended 2+ cores
Memory: Minimum 512MB, recommended 1GB+
Disk: Minimum 100MB
Network: Access to Kubernetes cluster and configured services

Software Requirements#

Go: 1.25+ (building from source)
Docker: 20.10+ (containerized deployment)
kubectl: Configured cluster access
Helm: 3.0+ (Helm deployment)

Service Dependencies#

Optional services to connect to:

Security Guide

Mon, 01 Jan 0001 00:00:00 +0000

Security Guide#

This document describes the security features and best practices for Cloud Native MCP Server.

Table of Contents#

Authentication
Secret Management
Input Sanitization
Audit Logging
Security Best Practices
Security Headers
Reporting Security Issues

Authentication#

API Key Authentication#

API keys must meet the following complexity requirements:

Minimum Length: 16 characters
Character Types: Must include at least 3 of the following 4 types:
- Uppercase letters (A-Z)
- Lowercase letters (a-z)
- Numbers (0-9)
- Special characters (!@#$%^&*()_+-=[]{}|;:,.<>?)

Valid Examples:

Performance Guide

Mon, 01 Jan 0001 00:00:00 +0000

Performance Guide#

This guide focuses on performance tuning that matches the current Cloud Native MCP Server implementation.

What You Can Tune Today#

1. Server Timeouts#

1
2
3
4


server:
 readTimeoutSec: 30
 writeTimeoutSec: 0
 idleTimeoutSec: 60

Recommendations:

Keep writeTimeoutSec: 0 for SSE-heavy workloads.
Increase readTimeoutSec for slow clients or large request bodies.
Increase idleTimeoutSec for long-lived clients behind proxies.

2. Kubernetes Client Throughput#

1
2
3
4


kubernetes:
 timeoutSec: 30
 qps: 100.0
 burst: 200

Recommendations:

Tools Reference

Mon, 01 Jan 0001 00:00:00 +0000

Tools Reference#

Cloud Native MCP Server provides 220+ powerful tools covering Kubernetes management, application deployment, monitoring, log analysis, and more.

### 🚀 Kubernetes (28 tools) Core container orchestration and resource management

### 📦 Helm (31 tools) Application package management and deployment

### 📊 Grafana (36 tools) Visualization, monitoring dashboards, and alerting

### 📈 Prometheus (20 tools) Metrics collection, querying, and monitoring

### 🔍 Kibana (52 tools) Log analysis, visualization, and data exploration

### ⚡ Elasticsearch (14 tools) Log storage, search, and data indexing

### ⚠️ Alertmanager (15 tools) Alert rules management and notifications

### 📍 Jaeger (8 tools) Distributed tracing and performance analysis

### 🌐 OpenTelemetry (9 tools) Metrics, traces, and logs collection and analysis

### 🔧 Utilities (6 tools) General-purpose utility tools

Kubernetes Tools (28)#

The Kubernetes service provides comprehensive cluster management capabilities:

API Documentation

Mon, 01 Jan 0001 00:00:00 +0000

API Documentation#

This page documents the runtime endpoints exposed by Cloud Native MCP Server.

Base Address#

1

http://localhost:8080

Transport Modes and Endpoints#

Cloud Native MCP Server supports two runtime modes:

Mode	Typical Usage	Aggregate Endpoint
`sse`	Broad MCP client compatibility	`/api/aggregate/sse`
`streamable-http`	Modern MCP transport	`/api/aggregate/streamable-http`

Service-specific endpoint pattern:

SSE: /api/<service>/sse
Streamable HTTP: /api/<service>/streamable-http

Common service names include kubernetes, helm, grafana, prometheus, kibana, elasticsearch, alertmanager, jaeger, opentelemetry, utilities, and aggregate.