文档中心 on 云原生 MCP 服务器

快速开始

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

快速开始#

该页面位于 docs/ 路径下，作为快速开始入口页使用。

如果你希望按完整流程阅读，请优先进入：

30 秒可用性检查#

1
2
3
4
5


# 健康检查
curl -sS http://127.0.0.1:8080/health

# SSE 握手 + initialize 全链路检查（仓库根目录执行）
make sse-smoke BASE_URL=http://127.0.0.1:8080

常用入口#

SSE 聚合端点（--mode=sse）: http://127.0.0.1:8080/api/aggregate/sse
Streamable-HTTP 聚合端点（--mode=streamable-http）: http://127.0.0.1:8080/api/aggregate/streamable-http
健康检查: http://127.0.0.1:8080/health

架构指南

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

架构指南#

本文档描述 Cloud Native MCP Server 的系统架构和设计原则。

概述#

Cloud Native MCP Server 是一个高性能的 Model Context Protocol (MCP) 服务器，用于管理 Kubernetes 和云原生基础设施。它采用模块化设计，支持多种运行模式和协议。

架构目标#

高性能: 优化的缓存、连接池和资源管理
可扩展性: 模块化设计，易于添加新服务
安全性: 多层认证、输入清理和审计日志
可观测性: 内置指标、日志和追踪
可靠性: 健康检查、重试机制和优雅降级

系统架构#

┌─────────────────────────────────────────────────────────────┐
│ 客户端 │
│ (Claude Desktop, Browser, Custom MCP Clients) │
└────────────────────┬────────────────────────────────────────┘
 │
 │ MCP Protocol (SSE/Streamable-HTTP)
 │
┌────────────────────▼────────────────────────────────────────┐
│ HTTP Server │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 路由层 (SSE/Streamable-HTTP) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 中间件层 │ │
│ │ - 认证 (API Key/Bearer/Basic) │ │
│ │ - 审计日志 │ │
│ │ - 速率限制 │ │
│ │ - 安全中间件 │ │
│ │ - 指标收集 │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ 服务管理层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Kubernetes│ │ Helm │ │ Grafana │ │Prometheus│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Kibana │ │Elastic │ │ AlertMgr │ │ Jaeger │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Otel │ │Utilities │ │
│ └──────────┘ └──────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ 基础设施层 │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 缓存层 (LRU/Segmented) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 密钥管理 │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 日志系统 │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 指标系统 │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────────┘
 │
 │
┌────────────────────▼────────────────────────────────────────┐
│ 外部服务 │
│ Kubernetes Cluster, Grafana, Prometheus, ES, etc. │
└─────────────────────────────────────────────────────────────┘

核心组件#

1. HTTP 服务器#

职责: 处理传入的 HTTP/SSE 请求和连接

配置指南

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

配置指南#

本指南涵盖 Cloud Native MCP Server 的所有配置选项。

目录#

配置方法
服务器配置
服务配置
认证配置
日志配置
审计日志
缓存配置
性能调优
示例配置

配置方法#

K8s MCP Server 支持三种配置方法（按优先级排序）：

命令行参数 - 最高优先级
环境变量 - 中等优先级
YAML 配置文件 - 最低优先级

配置优先级示例#

1
2
3
4
5
6
7


# 配置文件设置默认值
# 环境变量覆盖配置文件
# 命令行参数覆盖所有设置

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

服务器配置#

基本设置#

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


server:
 # 运行模式: sse | streamable-http
 # 推荐生产环境使用 streamable-http，兼容性优先可使用 sse
 mode: "sse"

 # 服务器监听地址
 addr: "0.0.0.0:8080"

 # HTTP 读取超时（秒）
 # 0 = 无超时（生产环境不推荐）
 # 推荐: 30-60 秒
 readTimeoutSec: 30

 # HTTP 写入超时（秒）
 # SSE 连接应设置为 0 以保持连接
 writeTimeoutSec: 0

 # HTTP 空闲超时（秒）
 # 默认: 60 秒
 idleTimeoutSec: 60

SSE 路径配置#

 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 端点
 kubernetes: "/api/kubernetes/sse"

 # Grafana SSE 端点
 grafana: "/api/grafana/sse"

 # Prometheus SSE 端点
 prometheus: "/api/prometheus/sse"

 # Kibana SSE 端点
 kibana: "/api/kibana/sse"

 # Helm SSE 端点
 helm: "/api/helm/sse"

 # Alertmanager SSE 端点
 alertmanager: "/api/alertmanager/sse"

 # Elasticsearch SSE 端点
 elasticsearch: "/api/elasticsearch/sse"

 # OpenTelemetry SSE 端点
 opentelemetry: "/api/opentelemetry/sse"

 # Utilities SSE 端点
 utilities: "/api/utilities/sse"

 # 聚合所有服务的 SSE 端点
 aggregate: "/api/aggregate/sse"

Streamable-HTTP 路径配置#

 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 端点
 kubernetes: "/api/kubernetes/streamable-http"

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

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

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

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

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

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

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

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

 # 聚合所有服务的 Streamable-HTTP 端点
 aggregate: "/api/aggregate/streamable-http"

命令行参数#

参数	描述	默认值
`--mode`	服务器模式 (sse, streamable-http)	sse
`--addr`	监听地址	0.0.0.0:8080
`--config`	配置文件路径	config.yaml
`--log-level`	日志级别 (debug, info, warn, error)	info

环境变量#

变量	描述	默认值
`MCP_MODE`	服务器模式	sse
`MCP_ADDR`	监听地址	0.0.0.0:8080
`MCP_LOG_LEVEL`	日志级别	info

服务配置#

Kubernetes#

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


kubernetes:
 # kubeconfig 文件路径
 # 如果为空，使用默认: $KUBECONFIG → ~/.kube/config → service account
 kubeconfig: ""

 # 单个 API 调用超时（秒）
 timeoutSec: 30

 # API 客户端每秒查询数 (QPS)
 qps: 100.0

 # API 客户端突发速率
 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:
 # 启用/禁用 Prometheus 服务
 enabled: false

 # Prometheus 服务器地址
 # 格式: http://host:port 或 https://host:port
 address: "http://localhost:9090"

 # 请求超时（秒）
 timeoutSec: 30

 # Basic auth 用户名（可选）
 username: ""

 # Basic auth 密码（可选）
 password: ""

 # Bearer token 认证（可选，优先级高于 Basic Auth）
 bearerToken: ""

 # 跳过 TLS 证书验证
 # 生产环境不要使用！
 tlsSkipVerify: false

 # TLS 客户端证书文件路径（用于 mTLS 认证）
 tlsCertFile: ""

 # TLS 客户端密钥文件路径
 tlsKeyFile: ""

 # TLS CA 证书文件路径
 tlsCAFile: ""

Grafana#

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


grafana:
 # 启用/禁用 Grafana 服务
 enabled: false

 # Grafana 服务器 URL
 # 格式: http://host:port 或 https://host:port
 url: "http://localhost:3000"

 # Grafana API Key（推荐）
 # 在 Grafana 中创建: Administration → API Keys
 apiKey: ""

 # Basic auth 用户名（API Key 的替代方案）
 username: ""

 # Basic auth 密码
 password: ""

 # 请求超时（秒）
 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:
 # 启用/禁用 Kibana 服务
 enabled: false

 # Kibana 服务器 URL
 # 格式: http://host:port 或 https://host:port
 url: "https://localhost:5601"

 # Kibana API Key（推荐）
 # 在 Kibana 中创建: Stack Management → API Keys
 apiKey: ""

 # Basic auth 用户名（API Key 的替代方案）
 username: ""

 # Basic auth 密码
 password: ""

 # 请求超时（秒）
 timeoutSec: 30

 # 跳过 TLS 证书验证
 # 生产环境不要使用！
 skipVerify: false

 # Kibana 空间名称
 # 默认: "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:
 # 启用/禁用 Helm 服务
 enabled: false

 # Helm 操作 kubeconfig 路径
 # 如果为空，使用与 Kubernetes 客户端相同的 kubeconfig
 kubeconfigPath: ""

 # Helm 操作默认命名空间
 namespace: "default"

 # 启用 Helm 调试模式
 debug: false

 # 仓库更新超时（秒）
 # 默认: 300 (5 分钟)
 # 国内环境推荐: 600-900
 timeoutSec: 300

 # 最大重试次数
 # 失败的仓库更新的重试次数
 # 默认: 3
 # 推荐: 3-5
 maxRetries: 3

 # 启用镜像
 # 用于加速 Helm 仓库拉取
 # 默认: false
 useMirrors: false

 # 自定义镜像映射
 # 格式: 原始仓库 URL -> 镜像 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:
 # 启用/禁用 Elasticsearch 服务
 enabled: false

 # Elasticsearch 服务器地址（支持多节点高可用）
 addresses:
 - "http://localhost:9200"

 # 单个 Elasticsearch 服务器地址（addresses 的替代方案）
 # 当 addresses 为空时使用
 address: ""

 # Basic auth 用户名
 username: ""

 # Basic auth 密码
 password: ""

 # Bearer token 认证（可选，优先级高于 Basic Auth）
 bearerToken: ""

 # API Key 认证（可选，最高优先级）
 # 格式: id:api_key
 apiKey: ""

 # 请求超时（秒）
 timeoutSec: 30

 # 跳过 TLS 证书验证
 # 生产环境不要使用！
 tlsSkipVerify: false

 # TLS 客户端证书文件路径（用于 mTLS 认证）
 tlsCertFile: ""

 # TLS 客户端密钥文件路径
 tlsKeyFile: ""

 # TLS CA 证书文件路径
 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:
 # 启用/禁用 Alertmanager 服务
 enabled: false

 # Alertmanager 服务器地址
 # 格式: http://host:port 或 https://host:port
 address: "http://localhost:9093"

 # 请求超时（秒）
 timeoutSec: 30

 # Basic auth 用户名（可选）
 username: ""

 # Basic auth 密码（可选）
 password: ""

 # Bearer token 认证（可选，优先级高于 Basic Auth）
 bearerToken: ""

 # 跳过 TLS 证书验证
 # 生产环境不要使用！
 tlsSkipVerify: false

 # TLS 客户端证书文件路径（用于 mTLS 认证）
 tlsCertFile: ""

 # TLS 客户端密钥文件路径
 tlsKeyFile: ""

 # TLS CA 证书文件路径
 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:
 # 启用/禁用 OpenTelemetry 服务
 enabled: false

 # OpenTelemetry Collector 地址
 # 格式: http://host:port 或 https://host:port
 address: "http://localhost:4318"

 # 请求超时（秒）
 timeoutSec: 30

 # Basic auth 用户名（可选）
 username: ""

 # Basic auth 密码（可选）
 password: ""

 # Bearer token 认证（可选，优先级高于 Basic Auth）
 bearerToken: ""

 # 跳过 TLS 证书验证
 # 生产环境不要使用！
 tlsSkipVerify: false

 # TLS 客户端证书文件路径（用于 mTLS 认证）
 tlsCertFile: ""

 # TLS 客户端密钥文件路径
 tlsKeyFile: ""

 # TLS CA 证书文件路径
 tlsCAFile: ""

Utilities#

1
2
3


utilities:
 # Utilities 服务始终启用
 enabled: true

认证配置#

API Key 认证#

 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:
 # 启用/禁用认证
 enabled: false

 # 认证模式: apikey | bearer | basic
 # apikey: X-API-Key 简单 API 密钥认证
 # bearer: Bearer Token (JWT) 认证
 # basic: HTTP Basic Auth
 mode: "apikey"

 # API Key（用于 apikey 模式）
 # 最少 8 字符，推荐 16+ 字符
 apiKey: ""

 # Bearer token（用于 bearer 模式）
 # 最少 16 字符推荐（JWT token）
 bearerToken: ""

 # Basic Auth 用户名
 username: ""

 # Basic Auth 密码
 password: ""

 # JWT 密钥（用于 JWT 验证）
 jwtSecret: ""

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

认证环境变量#

变量	描述
`MCP_AUTH_ENABLED`	启用认证 (1, true, yes, on)
`MCP_AUTH_MODE`	认证模式 (apikey, bearer, basic)
`MCP_AUTH_API_KEY`	API key 或 bearer token
`MCP_AUTH_USERNAME`	Basic auth 用户名
`MCP_AUTH_PASSWORD`	Basic auth 密码
`MCP_AUTH_JWT_SECRET`	JWT 密钥
`MCP_AUTH_JWT_ALGORITHM`	JWT 算法

日志配置#

1
2
3
4
5
6
7


logging:
 # 日志级别: debug | info | warn | error
 level: "info"

 # 使用 JSON 格式日志
 # 适用于日志聚合系统 (ELK, Splunk, etc.)
 json: false

日志级别说明#

debug: 详细的调试信息，包括所有请求和响应
info: 一般信息，包括重要操作和状态变化
warn: 警告信息，不影响功能但需要注意
error: 错误信息，功能受损

审计日志#

基本配置#

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


audit:
 # 启用/禁用审计日志
 enabled: false

 # 审计日志级别: debug | info | warn | error
 level: "info"

 # 审计日志存储: stdout | file | database | all
 storage: "memory"

 # 日志格式: text | json
 # json: 结构化 JSON 格式，适合日志聚合
 # text: 人类可读的文本格式
 format: "json"

 # 最大查询结果数
 maxResults: 1000

 # 查询时间范围（天）
 timeRange: 90

文件存储配置#

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


audit:
 storage: "file"
 file:
 # 日志文件路径
 path: "/var/log/cloud-native-mcp-server/audit.log"

 # 最大日志文件大小 (MB)
 maxSizeMB: 100

 # 最大备份文件数
 maxBackups: 10

 # 最大日志文件年龄（天）
 maxAgeDays: 30

 # 压缩轮转的日志文件
 compress: true

 # 内存存储的最大日志数
 maxLogs: 10000

数据库存储配置#

 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:
 # 数据库类型: sqlite | postgresql | mysql
 type: "sqlite"

 # SQLite 数据库文件路径
 # 仅当 type="sqlite" 时使用
 sqlitePath: "/var/lib/cloud-native-mcp-server/audit.db"

 # PostgreSQL 连接字符串
 # 仅当 type="postgresql" 时使用
 # 格式: postgresql://user:password@host:port/dbname
 connectionString: ""

 # 数据库表名
 tableName: "audit_logs"

 # 最大记录数
 maxRecords: 100000

 # 清理间隔（小时）
 cleanupInterval: 24

查询 API 配置#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


audit:
 query:
 # 启用查询 API
 enabled: true

 # 每个查询的最大结果数
 maxResults: 1000

 # 最大时间范围（天）
 timeRange: 90

敏感数据掩码配置#

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


audit:
 masking:
 # 启用掩码
 enabled: true

 # 要掩码的字段
 fields:
 - password
 - token
 - apiKey
 - secret
 - passwd
 - pwd
 - authorization

 # 掩码替换值
 maskValue: "***REDACTED***"

采样配置（高流量场景）#

1
2
3
4
5
6
7
8


audit:
 sampling:
 # 启用采样
 enabled: false

 # 采样率 (0-1)
 # 1.0 = 记录所有, 0.1 = 记录 10%
 rate: 1.0

服务和工具过滤#

1
2
3
4
5
6
7
8
9


enableDisable:
 # 禁用的服务（逗号分隔）
 disabledServices: []

 # 启用的服务（逗号分隔，覆盖禁用列表）
 enabledServices: []

 # 禁用的工具（逗号分隔）
 disabledTools: []

性能调优#

使用当前版本已支持的调优项：

部署指南

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

部署指南#

本指南涵盖 Cloud Native MCP Server 的各种部署策略和最佳实践。

目录#

前提条件
快速部署
Kubernetes 部署
Docker 部署
Helm 部署
生产环境考虑
监控和可观测性
安全最佳实践
故障排查

前提条件#

系统要求#

操作系统: Linux, macOS, 或 Windows
CPU: 最低 1 核，推荐 2+ 核
内存: 最低 512MB，推荐 1GB+
磁盘: 最低 100MB
网络: 可访问 Kubernetes 集群和配置的服务

软件要求#

Go: 1.25+ (从源码构建)
Docker: 20.10+ (容器化部署)
kubectl: 已配置集群访问
Helm: 3.0+ (Helm 部署)

服务依赖#

可选连接的服务：

Grafana (可选)
Prometheus (可选)
Kibana (可选)
Elasticsearch (可选)
Alertmanager (可选)
Jaeger (可选)
OpenTelemetry (可选)

快速部署#

二进制部署#

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


# 下载最新版本
wget https://github.com/mahmut-Abi/cloud-native-mcp-server/releases/latest/download/cloud-native-mcp-server-linux-amd64
chmod +x cloud-native-mcp-server-linux-amd64

# 创建配置
cat > config.yaml << EOF
server:
 mode: "sse"
 addr: "0.0.0.0:8080"

logging:
 level: "info"

kubernetes:
 kubeconfig: ""
EOF

# 运行
./cloud-native-mcp-server-linux-amd64

Docker 快速启动#

1
2
3
4
5


docker run -d \
 --name cloud-native-mcp-server \
 -p 8080:8080 \
 -v ~/.kube:/root/.kube:ro \
 mahmutabi/cloud-native-mcp-server:latest

Kubernetes 部署#

基本部署#

创建部署清单：

安全指南

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

安全指南#

本文档描述了 Cloud Native MCP Server 的安全特性和最佳实践。

目录#

认证
密钥管理
输入清理
审计日志
安全最佳实践
安全头部
报告安全问题

认证#

API Key 认证#

API 密钥必须满足以下复杂度要求：

最小长度: 16 个字符
字符类型: 以下 4 种类型中至少包含 3 种：
- 大写字母 (A-Z)
- 小写字母 (a-z)
- 数字 (0-9)
- 特殊字符 (!@#$%^&*()_+-=[]{}|;:,.<>?)

有效示例:

Abc123!@#Xyz789!@# (大写、小写、数字、特殊字符)
Abc123Xyz789Abc123 (大写、小写、数字)
ABC123!@#XYZ789!@# (大写、数字、特殊字符)

无效示例:

Abc123!@# (少于 16 个字符)
abcdefgh12345678 (只有小写和数字，不满足 3 种字符类型)
ABCDEFGHIJKLMNOPQRSTUVWXYZ (只有大写)

Bearer Token 认证#

Bearer token 必须遵循 JWT 结构：

格式: header.payload.signature
最小长度: 32 个字符
编码: Base64URL 编码的各部分
验证: 每个部分必须只包含有效的 base64url 字符 (A-Z, a-z, 0-9, -, _, +)

有效示例:

性能指南

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

性能指南#

本指南仅包含与当前 Cloud Native MCP Server 实现一致的性能调优项。

当前可调优项#

1. 服务器超时#

1
2
3
4


server:
 readTimeoutSec: 30
 writeTimeoutSec: 0
 idleTimeoutSec: 60

建议：

SSE 场景保持 writeTimeoutSec: 0。
客户端较慢或请求体较大时，适当提高 readTimeoutSec。
长连接场景适当提高 idleTimeoutSec。

2. Kubernetes 客户端吞吐#

1
2
3
4


kubernetes:
 timeoutSec: 30
 qps: 100.0
 burst: 200

建议：

工具参考

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

工具参考#

Cloud Native MCP Server 提供 220+ 个强大的工具，覆盖 Kubernetes 管理和应用部署、监控、日志分析等各个方面。

Kubernetes 工具（28 个）#

Pod 管理#

list_pods - 列出 Pod
get_pod - 获取 Pod 详情
describe_pod - 描述 Pod 状态
delete_pod - 删除 Pod
get_pod_logs - 获取 Pod 日志
get_pod_events - 获取 Pod 事件

Deployment 管理#

list_deployments - 列出 Deployment
get_deployment - 获取 Deployment 详情
create_deployment - 创建 Deployment
update_deployment - 更新 Deployment
delete_deployment - 删除 Deployment
scale_deployment - 扩缩容 Deployment
restart_deployment - 重启 Deployment

Service 管理#

list_services - 列出 Service
get_service - 获取 Service 详情
create_service - 创建 Service
delete_service - 删除 Service

ConfigMap & Secret#

list_configmaps - 列出 ConfigMap
get_configmap - 获取 ConfigMap 详情
create_configmap - 创建 ConfigMap
list_secrets - 列出 Secret
get_secret - 获取 Secret 详情
create_secret - 创建 Secret

命名空间#

list_namespaces - 列出命名空间
get_namespace - 获取命名空间详情
create_namespace - 创建命名空间

节点管理#

list_nodes - 列出节点
get_node - 获取节点详情
describe_node - 描述节点状态

资源状态#

get_resource_usage - 获取资源使用情况
get_cluster_info - 获取集群信息

Helm 工具（31 个）#

Chart 管理#

list_repositories - 列出 Helm 仓库
add_repository - 添加 Helm 仓库
remove_repository - 移除 Helm 仓库
update_repository - 更新 Helm 仓库
search_chart - 搜索 Chart
show_chart - 显示 Chart 详情
pull_chart - 下载 Chart

Release 管理#

list_releases - 列出 Release
get_release - 获取 Release 详情
install_chart - 安装 Chart
upgrade_release - 升级 Release
rollback_release - 回滚 Release
uninstall_release - 卸载 Release
get_release_history - 获取 Release 历史
get_release_status - 获取 Release 状态
get_release_values - 获取 Release 配置值

Values 管理#

get_values - 获取配置值
set_values - 设置配置值
diff_values - 比较配置值差异

Release 操作#

test_release - 测试 Release
lint_chart - 检查 Chart
package_chart - 打包 Chart
verify_chart - 验证 Chart
template_chart - 生成模板

Chart 依赖#

list_dependencies - 列出依赖
update_dependencies - 更新依赖

插件管理#

list_plugins - 列出插件
install_plugin - 安装插件

版本管理#

list_versions - 列出 Chart 版本
get_version_info - 获取版本信息

调试工具#

debug_release - 调试 Release

Grafana 工具（36 个）#

仪表板管理#

list_dashboards - 列出仪表板
get_dashboard - 获取仪表板详情
create_dashboard - 创建仪表板
update_dashboard - 更新仪表板
delete_dashboard - 删除仪表板
import_dashboard - 导入仪表板
export_dashboard - 导出仪表板
search_dashboards - 搜索仪表板
get_dashboard_by_uid - 通过 UID 获取仪表板
get_dashboard_by_tag - 通过标签获取仪表板

数据源管理#

list_datasources - 列出数据源
get_datasource - 获取数据源详情
create_datasource - 创建数据源
update_datasource - 更新数据源
delete_datasource - 删除数据源
test_datasource - 测试数据源连接

文件夹管理#

list_folders - 列出文件夹
get_folder - 获取文件夹详情
create_folder - 创建文件夹
update_folder - 更新文件夹
delete_folder - 删除文件夹

查询执行#

execute_query - 执行查询
execute_multiple_queries - 执行多个查询
query_metrics - 查询指标

告警管理#

list_alerts - 列出告警
get_alert - 获取告警详情
pause_alert - 暂停告警
resume_alert - 恢复告警
get_alert_rules - 获取告警规则

用户管理#

list_users - 列出用户
get_user - 获取用户详情
create_user - 创建用户

组织管理#

list_organizations - 列出组织
get_organization - 获取组织详情

健康检查#

get_health - 获取健康状态
get_version - 获取版本信息

Prometheus 工具（20 个）#

查询执行#

query - 执行即时查询
query_range - 执行范围查询
query_exemplars - 查询示例数据

元数据查询#

label_names - 获取标签名
label_values - 获取标签值
series - 获取时间序列
metadata - 获取元数据

目标管理#

targets - 获取目标列表
get_target_metadata - 获取目标元数据

规则管理#

rules - 获取规则列表
get_alerts - 获取告警列表

配置管理#

config - 获取配置信息
flags - 获取启动参数

状态查询#

status - 获取状态信息
query_stats - 获取查询统计

快照管理#

snapshot - 创建快照

TSDB 操作#

tsdb_stats - 获取 TSDB 统计
tsdb_series - 获取 TSDB 序列

存储操作#

block_info - 获取块信息

Kibana 工具（52 个）#

索引管理#

list_indices - 列出索引
get_index - 获取索引详情
create_index - 创建索引
delete_index - 删除索引
get_index_stats - 获取索引统计
get_index_settings - 获取索引设置
update_index_settings - 更新索引设置

文档操作#

search_documents - 搜索文档
get_document - 获取文档
create_document - 创建文档
update_document - 更新文档
delete_document - 删除文档
bulk_operations - 批量操作

查询构建#

build_query - 构建查询
execute_query - 执行查询
aggregate_data - 聚合数据
get_query_stats - 获取查询统计

可视化#

list_visualizations - 列出可视化
get_visualization - 获取可视化
create_visualization - 创建可视化
update_visualization - 更新可视化
delete_visualization - 删除可视化

仪表板#

list_dashboards - 列出仪表板
get_dashboard - 获取仪表板
create_dashboard - 创建仪表板
update_dashboard - 更新仪表板
delete_dashboard - 删除仪表板

索引模式#

list_index_patterns - 列出索引模式
get_index_pattern - 获取索引模式
create_index_pattern - 创建索引模式
update_index_pattern - 更新索引模式
delete_index_pattern - 删除索引模式

保存查询#

list_saved_queries - 列出保存的查询
get_saved_query - 获取保存的查询
create_saved_query - 创建保存的查询
update_saved_query - 更新保存的查询
delete_saved_query - 删除保存的查询

空间管理#

list_spaces - 列出空间
get_space - 获取空间
create_space - 创建空间
update_space - 更新空间
delete_space - 删除空间

发现#

discover_data - 发现数据
get_field_capabilities - 获取字段能力

导出导入#

export_objects - 导出对象
import_objects - 导入对象

短链接#

create_short_url - 创建短链接

Elasticsearch 工具（14 个）#

索引管理#

list_indices - 列出索引
get_index - 获取索引
create_index - 创建索引
delete_index - 删除索引
get_index_stats - 获取索引统计

文档操作#

index_document - 索引文档
get_document - 获取文档
search_documents - 搜索文档
update_document - 更新文档
delete_document - 删除文档

集群管理#

get_cluster_health - 获取集群健康
get_cluster_stats - 获取集群统计
get_cluster_info - 获取集群信息

别名管理#

get_aliases - 获取别名

Alertmanager 工具（15 个）#

告警管理#

list_alerts - 列出告警
get_alert - 获取告警详情
get_alert_groups - 获取告警组
get_silences - 获取沉默规则
create_silence - 创建沉默规则
delete_silence - 删除沉默规则
expire_silence - 过期沉默规则

规则管理#

get_alert_rules - 获取告警规则
list_rule_groups - 列出规则组

配置管理#

get_config - 获取配置
get_status - 获取状态

通知管理#

list_notifications - 列出通知
get_receivers - 获取接收者配置
list_routes - 列出路由

健康检查#

get_health - 获取健康状态

Jaeger 工具（8 个）#

追踪查询#

get_trace - 获取追踪
search_traces - 搜索追踪
get_services - 获取服务列表
get_operations - 获取操作列表

依赖分析#

get_dependencies - 获取依赖关系

指标查询#

get_metrics - 获取指标

配置查询#

get_config - 获取配置
get_status - 获取状态

OpenTelemetry 工具（9 个）#

指标管理#

get_metrics - 获取指标
get_metric_data - 获取指标数据
list_metric_streams - 列出指标流

追踪管理#

get_traces - 获取追踪
search_traces - 搜索追踪

日志管理#

get_logs - 获取日志
search_logs - 搜索日志

配置管理#

get_config - 获取配置
get_status - 获取状态

Utilities 工具（6 个）#

通用工具#

base64_encode - Base64 编码
base64_decode - Base64 解码
json_parse - JSON 解析
json_stringify - JSON 序列化
timestamp - 获取时间戳
uuid - 生成 UUID

工具调用示例#

Kubernetes - 列出 Pod#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "tools/call",
 "params": {
 "name": "list_pods",
 "arguments": {
 "namespace": "default"
 }
 }
}

Helm - 安装 Chart#

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


{
 "jsonrpc": "2.0",
 "id": 2,
 "method": "tools/call",
 "params": {
 "name": "install_chart",
 "arguments": {
 "chart": "nginx-ingress",
 "repo": "https://kubernetes.github.io/ingress-nginx",
 "release": "my-nginx",
 "namespace": "ingress-nginx"
 }
 }
}

Prometheus - 查询指标#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "jsonrpc": "2.0",
 "id": 3,
 "method": "tools/call",
 "params": {
 "name": "query",
 "arguments": {
 "query": "up{job=\"kubernetes-pods\"}"
 }
 }
}

Grafana - 查询仪表板#

1
2
3
4
5
6
7
8
9


{
 "jsonrpc": "2.0",
 "id": 4,
 "method": "tools/call",
 "params": {
 "name": "list_dashboards",
 "arguments": {}
 }
}

工具参数说明#

所有工具都支持以下通用参数：

API 文档

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

API 文档#

本页面描述 Cloud Native MCP Server 当前版本实际暴露的运行时接口。

基础地址#

1

http://localhost:8080

运行模式与端点#

Cloud Native MCP Server 支持两种运行模式：

模式	典型用途	聚合端点
`sse`	MCP 客户端兼容性优先	`/api/aggregate/sse`
`streamable-http`	推荐的现代 MCP 传输方式	`/api/aggregate/streamable-http`

服务级端点模式：

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

常见 service 名称包括 kubernetes、helm、grafana、prometheus、kibana、elasticsearch、alertmanager、jaeger、opentelemetry、utilities、aggregate。

说明：当前服务不提供旧版 /v1/mcp/* 风格接口。

认证方式#

运行时启用认证示例：

1
2
3


export MCP_AUTH_ENABLED=true
export MCP_AUTH_MODE=apikey
export MCP_AUTH_API_KEY='ChangeMe-Strong-Key-123!'

支持模式：

apikey
bearer
basic

API Key#

建议优先使用 X-Api-Key 请求头，也支持 api_key 查询参数。

文档中心 on 云原生 MCP 服务器

快速开始

快速开始#

30 秒可用性检查#

常用入口#

推荐阅读顺序#

架构指南

架构指南#

目录#

概述#

架构目标#

系统架构#

核心组件#

1. HTTP 服务器#

配置指南

配置指南#

目录#

配置方法#

配置优先级示例#

服务器配置#

基本设置#

SSE 路径配置#

Streamable-HTTP 路径配置#

命令行参数#

环境变量#

服务配置#

Kubernetes#

Prometheus#

Grafana#

Kibana#

Helm#

Elasticsearch#

Alertmanager#

OpenTelemetry#

Utilities#

认证配置#

API Key 认证#

认证环境变量#

日志配置#

日志级别说明#

审计日志#

基本配置#

文件存储配置#

数据库存储配置#

查询 API 配置#

敏感数据掩码配置#

采样配置（高流量场景）#

服务和工具过滤#

性能调优#

部署指南

部署指南#

目录#

前提条件#

系统要求#

软件要求#

服务依赖#

快速部署#

二进制部署#

Docker 快速启动#

Kubernetes 部署#

基本部署#

安全指南

安全指南#

目录#

认证#

API Key 认证#

Bearer Token 认证#

性能指南

性能指南#

当前可调优项#

1. 服务器超时#

2. Kubernetes 客户端吞吐#

工具参考

工具参考#

Kubernetes 工具（28 个）#

Pod 管理#

Deployment 管理#

Service 管理#

ConfigMap & Secret#

命名空间#