MCP Server 服务端配置
本页说明如何在「系统设置 → MCP Server」中配置 MCP（Model Context Protocol）Server 的各项设置。智能体客户端接入步骤见快速开始。
版本说明
「MCP Server 设置」页的卡片式分区、测试连接、危险开关预警与 Agent 变更审批自 v4.2.2.0 起提供。
设置页分为三张卡片：服务总览、传输与限额、Prometheus 工具，下面按此顺序说明。
服务总览
启用 MCP Server
| 配置项 | 默认值 |
|---|---|
| 启用 MCP Server | false（默认关闭） |
开启后，MCP 端点才对外暴露；关闭时对 /mcp 的请求一律返回 HTTP 404。
MCP 端点路径为 /mcp，同时支持 POST（JSON-RPC over Streamable HTTP）与 GET（SSE 流式连接，供 opencode 等客户端使用）。
反向代理
若使用反向代理，请确保 /mcp 路径路由到 Kuboard 后端服务，而不是前端服务。
MCP 地址与测试连接
设置页会显示当前 MCP 地址（格式为「你的 Kuboard 访问地址 + /mcp」）。点复制可拷贝到剪贴板；点测试连接可验证地址可达，返回 200 / 401 / 405 均判定为「可达」（401 表示端点在线但需要鉴权）。
认证方式
MCP 端点使用与 Kuboard 一致的访问密钥（Access Key）鉴权，客户端在请求头中携带 Authorization: Bearer <AK>.<SK> 或 Kb-Access-Key: <AK>.<SK>。访问密钥在右上角用户菜单 → 访问密钥中创建；复制 MCP 配置时生成的片段会自动填充该请求头。
Agent 写操作强制审批
| 配置项 | 默认值 |
|---|---|
| 强制审批 Agent 写操作 | true（生产安全默认） |
开启（默认）：智能体的写操作（apply_k8s / delete_k8s / drain_node / evict_pod 等）会先暂存为变更计划，等你在 Kuboard UI 逐条审批，并把一次性审批令牌（approvalToken）回传给智能体后才会真正对集群生效。关闭：写调用立即直接执行，页面会出现红色警示横幅。
传输与限额
CORS 允许的 Origin
跨域浏览器客户端（如 https://chat.openai.com）需在此配置，否则其跨域请求会被拒绝。
| Origin 列表状态 | 行为 |
|---|---|
| 空列表（默认） | 拒绝所有跨域请求 |
| 非空 | 按 Origin 字符串精确匹配允许 |
每条必须以 http:// 或 https:// 开头（表单即时校验）。该配置仅作用于 MCP 端点，不影响主应用其它接口的跨域行为。
单请求体最大字节数
限制单个 MCP 请求（JSON-RPC 请求体）的最大字节数，默认 10 MB，超过上限返回 HTTP 413。AI 客户端发送较大工具参数时可适当调大，界面按 1MB 步长递增。
每用户限流
| 配置项 | 默认值 | 界面范围 |
|---|---|---|
| 每用户限流（窗口内最大请求数） | 50 次 | 1 ~ 10000 |
| 限流滑动窗口时长 | 60 秒 | 1 ~ 3600 秒 |
用户在滑动窗口内请求数超限，将返回 HTTP 429，客户端应据此退避重试。配置热生效，无需重启。
每用户最大 SSE 订阅数
限制每个用户同时持有的资源/提示变更订阅的并发上限，默认 100（单位：连接），超出后订阅申请返回错误。
保存后需重启
该值保存后需重启 Kuboard 服务才生效，界面亦有此提示。
Prometheus 工具
这一节控制 MCP 暴露的 Prometheus 指标查询工具（prometheus_query / prometheus_query_range 等）。
总开关
默认开启。关闭后工具仍会出现在工具列表中，但调用直接返回 PROM_NOT_FOUND，并跳过服务发现与逐条 RBAC 鉴权。
查询限额与鉴权
| 配置项 | 默认值 | 界面范围 |
|---|---|---|
| 单次瞬时查询最大 series 数 | 10000 条 | 1 ~ 1,000,000 |
| 单次范围查询最大 points 数 | 100000 个 | 1 ~ 10,000,000 |
| 查询超时 | 30 秒 | 1 ~ 600 |
| 逐条 RBAC 鉴权 | 开启 | 开关 |
聚合查询策略
为「过滤 + 聚合」类 PromQL（如 sum、avg、count、topk）提供三种策略：
| 策略 | 行为 |
|---|---|
| 拒绝聚合查询 | 命中聚合/函数直接拒绝 |
| 允许并按维度做 scope 鉴权（推荐，默认） | 聚合后按维度做并集 RBAC 鉴权 |
| 允许但强制 cluster scope | 聚合后强制 cluster-scope 权限 |
配套两项数值设置：
- 聚合查询限流倍率：聚合查询一次消耗该倍数的限流额度，默认 5 倍；
- 聚合查询最大维度展开：单次聚合查询最多展开的命名空间/节点维度数，默认 100，避免一条宽泛的聚合越权扫到全集群。
按集群 Prometheus 服务发现
MCP 在集群内定位 Prometheus 实例的位置。不添加任何行时使用内置启发式自动探测；如需覆盖，可按集群添加一条发现规则：
| 字段 | 说明 |
|---|---|
| 集群 ID | 要覆盖的集群（下拉选择） |
| 名称空间 | 仅服务名称模式生效，缺省跨命名空间查找 |
| 标签选择器 | 如 operated-prometheus=true；与服务名称二选一 |
| 服务名称 | 如 prometheus-operated；与标签选择器二选一，同时设置时标签选择器优先 |
| 端口 | Service 端口，缺省 9090 |
覆盖规则配置后立即生效。