MCP 集成

Lens 将其平台能力以 Model Context Protocol (MCP) 服务器的形式暴露出来，这样任何支持 MCP 的客户端都可以像内置的 Lens Assistant 一样检查和操作 Lens。MCP 层是一个瘦适配层：每一个工具都是通过环回地址调用 Lens 自身的 REST API——MCP 服务器中没有重新实现任何集群、认证或领域逻辑。

端点与传输方式

属性	值
方法 / 路径	`POST /api/mcp`（位于 Lens 的 BFF/Node 服务器上）
默认端口	`SERVER_PORT` / `PORT`（3000；如果 3000 已被占用，`scripts/lens-local.sh` 会选取其上方下一个空闲端口）
传输方式	MCP Streamable HTTP，JSON-RPC 2.0
会话	无状态——每个请求使用一个临时的 MCP 服务器，没有 `Mcp-Session-Id`
其他方法	`GET` / `DELETE /api/mcp` 返回 `405`（无状态模式下没有服务器到客户端的流）

该端点特意设计为无状态：它可以水平扩展，并且每一个工具都会重新从 REST API 读取实时数据，因此响应结果始终反映当前状态。

认证

POST /api/mcp 需要一个已登录的会话，该会话需持有以下权限之一：

mcp:tool:invoke，或者
playground:chat:use

可以通过浏览器 Cookie prism_session 或者通过 Bearer 令牌发送会话凭据：

Authorization: ******

<session-token> 是登录时颁发的 prism_session Cookie 的值（可以在登录状态下从浏览器开发者工具中读取）。请求会通过 GET /api/v1/auth/session 进行内省；未认证的调用会得到 401 unauthenticated，而没有上述权限的会话会得到 403。

备注

面向第三方 MCP 客户端的专用凭据（API 密钥 / OAuth 权限范围）是一项计划中的、独立的设计——目前外部客户端复用的是已登录的会话。相关的开放性问题请参阅 docs/design/mcp-playground-design.md（第 4 阶段）。

工具

工具目录是从 Lens 的 REST 接口生成的，并按领域分组。每个工具都带有一个 风险等级：

等级	含义	示例
`read`	只读查看	`list_clusters`、`list_deployments`、`get_deployment_pod_logs`、`get_flow_map_metrics`、`list_storage_volumes`、`search_huggingface_models`
`write`	会改变状态（创建 / 启动 / 停止 / 安装）	`create_simulation_task`、`start_cluster_bootstrap`、`create_standard_vllm_deployment_run`、`install_gpu_driver`、`create_ai_provider`
`approve`	具有破坏性；需要明确确认	`delete_cluster`、`delete_configuration_artifact`、`delete_deployment_execution`、`delete_evaluation_workflow`、`delete_ai_provider`

在运行时通过 tools/list 可以发现确切的、最新的工具列表（名称会随着模块演进而变化）。所有工具都返回 JSON；调用失败时会返回一个 MCP 错误结果（isError: true），其消息就是底层的 REST 错误信息。

连接客户端

MCP Inspector

启动 Lens 开发技术栈（scripts/lens-local.sh start）。
在 MCP Inspector 中选择 Streamable HTTP，URL 填写 http://<lens-host>:3000/api/mcp。
添加请求头 Authorization: ******，然后点击连接并列出工具。

通用 MCP 客户端配置

{
  "mcpServers": {
    "lens": {
      "type": "http",
      "url": "http://<lens-host>:3000/api/mcp",
      "headers": {
        "Authorization": "******"
      }
    }
  }
}

原生 JSON-RPC

BASE=http://<lens-host>:3000/api/mcp
H="Authorization: ******"

# 1) 握手
curl -s $BASE -H "$H" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":1,"method":"initialize",
  "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# 2) 列出工具
curl -s $BASE -H "$H" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) 调用一个只读工具
curl -s $BASE -H "$H" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"list_clusters","arguments":{}}}'

说明

工具分为只读/写入/需确认三种类型；approve 等级应当只在一个人工确认步骤之后才被调用（正如 Lens Assistant 的界面所做的那样）——智能体不得自动批准这类操作。
MCP 服务器从不直接与集群通信：它调用的是 Lens 的 REST 接口，而该接口应用的是与 UI 相同的认证、RBAC 和作用域规则。
由于该传输方式是无状态的，所以不需要每次调用都执行一次新的 initialize，但每个请求仍然必须携带上述凭据。

端点与传输方式​

认证​

工具​

连接客户端​

MCP Inspector​

通用 MCP 客户端配置​

原生 JSON-RPC​

说明​

端点与传输方式

认证

工具

连接客户端

MCP Inspector

通用 MCP 客户端配置

原生 JSON-RPC

说明