MCP 接入
外部 AI 助手（Claude Code、Codex、WorkBuddy 等）通过 MCP 使用平台的方法：签发令牌、权限范围、客户端配置片段，以及可调用的工具清单。
概述
Sight Data 内置 MCP 服务端。外部 AI 助手用令牌连接后，以令牌所属用户的身份使用平台：查数据源和表结构、读写报表草稿、分析访问与性能、调用平台接口。权限与该用户在网页上一致。
服务使用无状态的 Streamable HTTP 传输，地址为 /api/mcp，认证方式为请求头 Authorization: Bearer <令牌>。外部助手使用它们自己的大模型，不需要配置 AI 生成报表 中的模型。
功能入口
左侧一级菜单「AI」>「MCP 接入」。页面上方显示服务地址和各客户端的配置片段，下方为令牌列表，分「我的令牌」和「全部令牌」（管理员可见）两个页签。
操作步骤
- 由管理员在「MCP 接入」页点击「签发令牌」。
- 填写「名称」（用于区分用途，如「我的 Claude Code」）、勾选「额外权限」、选择「有效期」，点击「签发」。
- 弹窗显示令牌，点击「复制令牌」。之后也可以在列表中点击「查看」「复制」或「接入配置」再次取用。
- 把服务地址和令牌填进客户端。页面提供的配置片段如下表。
- 在客户端里让助手调用
whoami，确认身份、令牌范围和可执行的操作。
客户端配置片段
| 客户端 | 做法 |
|---|---|
| Claude Code | 在终端执行 claude mcp add --transport http --scope user sight-report <服务地址> --header "Authorization: Bearer <令牌>" |
| Codex | 在 ~/.codex/config.toml 中配置 [mcp_servers.sight-report]，url 填服务地址，bearer_token_env_var = "SIGHT_MCP_TOKEN"，并在 shell 中设置环境变量 SIGHT_MCP_TOKEN |
| 通用 JSON（WorkBuddy、Cursor 等） | 在客户端 MCP 配置中添加 mcpServers.sight-report，type 为 http，url 为服务地址，headers.Authorization 为 Bearer <令牌> |
| 仅支持本地命令的客户端（如 Claude Desktop） | 用 npx -y mcp-remote <服务地址> --header Authorization:${SIGHT_AUTH} 桥接，令牌放在环境变量 SIGHT_AUTH，值为 Bearer <令牌>，本机需安装 Node.js |
页面中的片段会按当前部署的服务地址生成，建议直接从页面复制。
参数说明
签发令牌
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
| 名称 | 令牌用途标识 | 最长 100 字符，必填 |
| 额外权限 | 在只读基础上追加的范围 | 见下表；都不勾即只读 |
| 有效期 | 令牌有效天数 | 页面可选 7、30、90、180、365 天；服务端范围为 1 到 365 天，未指定时 90 天 |
权限范围
| 范围 | 说明 |
|---|---|
| 只读（默认） | 查数据、读报表、调用平台的只读接口（日志、使用分析、性能等） |
| 写草稿 | 新建报表、改草稿、保存快照、丢弃草稿，不影响线上。报表的写草稿工具还要求令牌所属用户是管理员 |
| 发布 | 把草稿发布为线上版本，会影响报表查看者 |
| 平台管理 | 调用平台的写接口（用户、权限、调度、缓存、配置等），与网页权限一致 |
| 元数据库 | 对平台元数据库执行只读 SQL，仅管理员可用，凭据列脱敏 |
令牌操作
| 操作 | 说明 |
|---|---|
| 查看 / 复制 | 列表默认显示掩码，点击「查看」向服务端取明文，每次取用记录审计日志 |
| 接入配置 | 用该令牌生成各客户端的配置片段 |
| 改权限 | 管理员修改权限范围，令牌不变，客户端无需重新配置，下一次调用按新范围生效 |
| 吊销 | 令牌立即失效 |
可调用的工具
以下清单来自服务端注册的工具。实际可见的工具随令牌范围和部署的产品而定。
通用与数据
| 工具 | 说明 |
|---|---|
whoami |
当前身份、是否管理员、令牌范围 |
list_design_docs、read_design_doc |
平台设计规则文档 |
list_datasources、list_tables、describe_table、search_values |
数据源、表、表结构、字段取值 |
validate_sql、preview_sql、explain_sql |
校验、预览、执行计划，SQL 只能是单条只读 SELECT |
list_shared_datasets、preview_shared_dataset |
共享数据集及预览 |
报表
| 工具 | 说明 | 所需范围 |
|---|---|---|
list_reports、list_directories、get_report、get_report_outline |
列出、读取报表与目录结构 | 只读 |
validate_report_xml、check_report_datasets |
校验报表 XML、核对数据集字段 | 只读 |
compile_grid_ir、compile_document_ir、compile_dashboard_ir |
把 IR 编译为报表 XML | 只读 |
patch_grid_ir、patch_dashboard_ir |
对 IR 做增量修改 | 只读 |
create_report、update_report_draft、patch_dashboard_xml、snapshot_report、discard_report_draft |
新建报表、写草稿、局部改仪表盘、保存快照、丢弃草稿 | 写草稿 |
publish_report |
发布报表 | 发布 |
大屏
Sight Wall 部署提供大屏工具：list_screens、get_screen、get_screen_outline、get_screen_template、list_screen_templates、validate_screen_xml（只读），create_screen、update_screen_draft、discard_screen_draft（写草稿），publish_screen（发布）。
分析与平台接口
| 工具 | 说明 |
|---|---|
usage_overview、report_heat_ranking、list_user_activity、list_report_visits、report_performance、list_slow_sql、list_report_errors、dashboard_query_stats |
报表使用概况、热度、用户活跃、访问明细、性能、慢 SQL、错误、仪表盘查询统计 |
list_audit_logs、list_login_logs、tail_log_file、list_schedule_logs、runtime_status |
审计日志、登录日志、服务端日志尾部、调度日志、运行状态 |
list_api、describe_api、call_api |
检索、查看并调用平台的只读接口 |
call_api_write |
调用平台写接口，需要「平台管理」范围 |
list_metadata_tables、describe_metadata_table、query_metadata |
元数据库只读查询，需要管理员且令牌有「元数据库」范围 |
示例
让 Claude Code 排查慢报表：
- 管理员签发令牌，名称填「我的 Claude Code」，不勾额外权限，有效期 30 天。
- 在终端执行页面提供的
claude mcp add ...命令。 - 在 Claude Code 中提问"最近一周哪些报表最慢，对应的慢 SQL 是什么"。
- 助手调用
report_performance与list_slow_sql，返回排行和 SQL，全程只读，不修改任何报表。
注意事项
注意：令牌等同于所属用户的身份，请勿写入代码仓库或共享。泄露后应立即在列表中「吊销」。
注意：「发布」「平台管理」范围的令牌可以修改线上内容和平台配置。除非确有需要，建议只签发只读或写草稿令牌；助手在发布和删改前应先向用户确认。
注意：令牌到期后自动失效。MCP 服务被停用时，页面提示「MCP 服务已停用」，所有令牌暂时不可用，令牌本身保留，重新启用后恢复。
提示：「业务 MCP」是另一项功能：内置 AI 作为 MCP 客户端，去访问业务系统提供的 MCP 服务，与本文的服务端方向相反。
