Studio 托管 MCP Server 接入配置指南

Studio 托管 MCP Server 的接入过程，可以理解为三步：

• 在 Studio 中进入 MCP Servers 页面
• 创建用于接入的 Personal Access Token，并指定默认连接环境
• 把对应客户端的配置接入 Claude Desktop、Cursor、Cherry Studio 等 AI 客户端

这篇文档主要回答“如何接入”和“接入时需要注意什么”。

接入入口

MCP Server 的入口位于：

• Lakehouse 首页
• 左侧菜单 AI
• 点击 MCP Servers

点击后会打开一个新的 Console 页面，并弹出

Lakehouse MCP & CLI

配置弹窗。

这里既包含 Token 管理，也包含不同客户端的连接配置模板。

创建 Personal Access Token

在

Lakehouse MCP & CLI

弹窗中，先创建 Personal Access Token。

创建时需要填写或确认这些信息：

• Token 名称
• 有效期
• 默认环境
  • 地域
  • 工作空间
  • 集群
  • Schema（如有需要）

这里的默认环境很重要。它决定了 Agent 在不额外切换上下文时，默认访问的是哪个地域、工作空间、集群和 Schema。

Token 的几个关键点

明文 Token 只会显示一次

创建成功后，页面会展示一次完整 Token。页面关闭后，通常只会看到脱敏值，因此需要在创建成功当下立即复制并妥善保存。

Token 代表当前用户权限

这个 Token 本质上继承的是当前用户在 Studio 和 Lakehouse 中已有的权限。
它不是一个额外的“低权限代理账号”，而是把当前用户身份授权给 Agent 使用。

因此：

• 不要把 Token 发给无关人员
• 不要把 Token 明文放入公共仓库
• 如果怀疑泄露，应及时删除并重新创建

删除 Token 会立即影响已接入客户端

如果删除某个 Token，依赖它的 MCP 连接会立即失效。因此删除前需要先确认是否仍有客户端在使用它。

Token 过期与续期

创建 Token 时需要设置有效期。Token 到期后，依赖它的 MCP 连接会立即失效，客户端会收到鉴权失败的错误。

续期方式：在 Studio 的 MCP Servers 页面对已有 Token 直接续期，延长有效期后无需替换客户端配置，连接恢复正常。如果 Token 已经删除，则需要重新创建并在客户端配置中替换 Token 值，再重启客户端。

Claude Desktop 配置

Claude Desktop 的接入方式，是在本地

claude_desktop_config.json

中增加一个 MCP Server 配置项。

配置文件常见路径：

• macOS：

  ~/Library/Application Support/Claude/claude_desktop_config.json

  ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：

  %APPDATA%\\Claude\\claude_desktop_config.json

  %APPDATA%\\Claude\\claude_desktop_config.json

在 MCP Servers 页面切换到 Claude 配置分段后，可以复制模板配置，再把其中的 token 替换成自己刚刚创建时拿到的明文 Token。

示例：

{ "mcpServers": { "clickzetta-studio-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "https://cn-shanghai-alicloud-mcp.api.clickzetta.com/mcp", "--allow-http", "--transport", "http", "--header", "X-Lakehouse-Token: Bearer <your_token>" ] } } }

如果本机里 Claude Desktop 无法正确找到

npx

，可以把

command

改成

npx

的绝对路径。

Cherry Studio 配置

如果使用 Cherry Studio，可以在 MCP 设置中新增一个基于 HTTP 的服务端配置。

通常需要填写：

• 服务名称
• MCP Server 地址
• 请求头中的 Token 信息

这类客户端不一定要求本地运行

npx

，但仍然需要正确填写 Token 和服务地址。

接入后如何验证

接入完成后，建议先做一个简单验证，而不是立刻开始复杂任务。

例如，可以先让 Agent 执行下面这类问题：

• 列出当前工作空间中的文件夹
• 列出当前工作空间有哪些数据源
• 查看

  public

  public
  schema 下有哪些表

如果这些结构化查询能返回结果，通常说明 MCP 已经接通，而且默认环境配置也是对的。

接入后的典型能力

完成接入后，Agent 通常可以开始做这些事：

• 查询 Lakehouse 元数据
• 读取和创建 Studio 目录与任务
• 保存任务内容和任务配置
• 发布任务、临时执行任务
• 读取任务实例、attempt 和执行日志

这些能力的实际使用方式，建议继续阅读：

• Studio MCP 任务开发与运行诊断指南

常见接入问题

Claude Desktop 找不到

npx

npx

如果 Claude Desktop 报错找不到

npx

或无法拉起本地命令，优先检查：

• 本机是否已安装 Node.js
• Terminal 中

  node -v

  node -v
  、

  npx -v

  npx -v
  是否正常
• Claude Desktop 使用

  npx

  npx
  时，是否需要改为绝对路径

已经接入但没有看到新工具

在某些客户端中，新增 MCP Server 后需要重启客户端或重开会话，工具列表才会刷新。

连接成功但访问的不是预期环境

这通常与创建 Token 时设置的默认环境有关。
如果默认工作空间、VC 或 Schema 配错了，Agent 虽然能连上，但会在错误的上下文里执行查询或操作。

相关文档

• MCP Server（由 Studio 托管，推荐） — 总览页，包含建议阅读路径
• Studio MCP 能力总览 — 了解接入后可以做什么
• Studio MCP 任务开发与运行诊断指南 — 接入后的第一个实操场景
• Studio MCP 最佳实践 — 日常使用原则