平台 MCP 接入：令牌、OAuth 与 Streamable HTTP

最后更新: 2026/11/2

让外部智能体通过 MCP 使用 Sight DataLink：个人访问令牌、按需暴露工具集、OAuth 2.1 授权、SSE 进度与取消、只读模式。

概述

平台自带一个 MCP 服务（Streamable HTTP），让外部智能体（Claude Desktop、Cursor、Claude Code 等）用对话的方式操作平台。想把某几个查询发布给智能体，用数据服务的 MCP 应用；想让智能体使用整个平台，用本文的平台级 MCP。

端点与能力

端点	用途
`POST /mcp`	平台级 MCP，使用个人访问令牌或 OAuth 令牌鉴权
`POST /mcp/apps/{id}`	应用级 MCP，对应数据服务里的 MCP 应用

平台级 MCP 提供三类能力：

工具：覆盖全部模块的操作（连接、管道、任务、运行、检测、对账、实时任务、通知、配置导入导出等）。
资源：datalink:// 前缀，包括表结构、样例行、运行日志、血缘等。
提示词（prompts）：失败诊断、创建同步管道等现成工作流。

创建个人访问令牌

权限与入口：每个账号都能管理自己的令牌。菜单：右上角账号菜单 → MCP 接入

平台自带一个 MCP 服务（Streamable HTTP，地址 /mcp），让外部智能体（Claude Desktop、Cursor、Claude Code 等）用对话的方式操作平台：它提供覆盖各模块的工具、datalink:// 资源（表结构、样例数据、运行日志、血缘等）和现成的工作流提示。接入需要一个个人访问令牌。令牌同样可以用于调用 REST 接口和触发 Webhook。

MCP 接入与访问令牌

图：MCP 接入

图中编号说明：

创建令牌：填名称、选范围与有效期。
复制配置模板：页面上方给出 MCP 地址和客户端配置片段，把 <你的访问令牌> 换成刚创建的令牌即可粘贴到客户端。
撤销：令牌泄露或不再使用时立即撤销，撤销后马上失效。

范围：「只读」只保留各模块的查看权限；「读写」等同你本人的写权限。令牌按所有者当前的权限鉴权：账号被禁用、改密或降权后，令牌会立即失效或降权；令牌永远不能管理账号，也拿不到脚本节点权限。
有效期1–365 天，建议总是填写，不要创建永不过期的令牌；每人最多 20 个有效令牌。令牌以 fdlp_ 开头，只在创建时显示一次，服务端只存哈希。
按需暴露：在 MCP 地址后加 ?toolsets=tasks,pipelines 只开放部分模块；加 ?readonly=true 隐藏全部写操作；加 ?mode=discovery 只暴露搜索 / 描述 / 调用三个元工具以节省上下文。
不方便保存令牌的第三方客户端，也可以走 OAuth 2.1 授权码 + PKCE 与动态客户端注册：授权页会展示客户端名称与范围（mcp:write 带醒目警告），同意后签发短期令牌。
运维抓取 Prometheus 指标时，推荐用运维账号的「只读」令牌，而不是管理员密码。

安全：令牌等同于你的账号：不要贴进聊天、工单或代码仓库；自动化脚本用「只读」+ 短有效期；用完撤销。

只读与按需暴露

?readonly=true 的连接按只读处理，run_sql 不能写；只读（read 范围）令牌不能调用「任何登录账号都可改」的接口。
?toolsets=tasks,pipelines 只开放部分模块；?mode=discovery 只暴露 search / describe / invoke 三个元工具，节省模型上下文。
单条消息大小有上限（默认 4096 KB），导出结果过大时会提示分批。
工具调用参数出错时，用 describe 查看工具的 schema。

OAuth 2.1 授权

除了个人访问令牌（Authorization: Bearer fdlp_...），平台 MCP 也支持 OAuth 2.1 授权码加 PKCE（S256）和动态客户端注册（DCR），适合无法安全保存令牌的第三方智能体或 MCP 客户端。两种 Bearer 并行可用，个人令牌的行为不变。

环节	说明
发现（公开）	`GET /.well-known/oauth-protected-resource` 返回资源与授权服务器；`GET /.well-known/oauth-authorization-server` 返回授权、令牌、注册、撤销端点，支持 `code_challenge_methods_supported=["S256"]`，`scopes_supported=["mcp:read","mcp:write"]`。issuer 由 `FDL_MCP_OAUTH_ISSUER` 指定，未配置时按请求的协议、主机、端口推导
动态注册	`POST /oauth/register`，提交 `client_name`、`redirect_uris` 等。redirect_uri 必须是 http(s)、无 fragment，http 只允许 localhost / 127.0.0.1 / [::1]；单客户端最多 10 个；可用 `FDL_MCP_OAUTH_DCR_ENABLED=false` 关闭；端点按来源 IP 限流
授权	`GET /oauth/authorize`（带 `response_type=code`、`client_id`、`redirect_uri`、`state`、`code_challenge`、`code_challenge_method=S256`、`scope`）。已登录用户会看到同意页，显示客户端名与范围，`mcp:write` 有醒目警告；授权码 5 分钟内一次性有效
换取令牌	`POST /oauth/token`：`authorization_code`（code、redirect_uri、client_id、code_verifier）换取 `fdlo_` 开头的 access token 与 `fdlr_` 开头的 refresh token；`refresh_token` 方式会轮换，旧令牌立即失效。access token 默认 1 小时，refresh 默认 30 天（`FDL_MCP_OAUTH_ACCESS_TTL_SECONDS` / `FDL_MCP_OAUTH_REFRESH_TTL_SECONDS`）
撤销	`POST /oauth/revoke`，撤销后 `/mcp` 立即返回 401

范围与权限：mcp:read 是只读 MCP 视图，写工具不列出也不可调用；mcp:write 允许写工具，但仍受授权用户当前的平台权限约束，每次请求都从数据库重新加载用户权限，同意授权不会扩权。/mcp 的 401 响应带 WWW-Authenticate 头指向资源元数据，支持 OAuth 的客户端（含 mcp-remote）会自动完成注册与授权；手动配置时把授权、令牌端点指向本服务的 /oauth/...，范围填 mcp:read 或 mcp:read mcp:write。审计日志「MCP工具调用」会记录令牌类型与 OAuth 客户端 id，不记录令牌明文或哈希。

Streamable HTTP：SSE、进度与取消

兼容优先：Accept: application/json、不带 Accept 或 */* 仍返回单个 JSON 响应；只有显式 Accept: text/event-stream 才切换到 SSE，且没有会话 ID。
SSE 帧：每帧为 event: message 加一行 data: <JSON-RPC 消息> 和空行，最后一个响应帧后关闭流。
进度：tools/call 的 params._meta.progressToken 非空时，先发送 notifications/progress，再发最终响应。
取消：客户端另发一个普通 JSON POST：{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":<原请求 id>}}。在途请求会被中断并以 JSON-RPC -32800 结束；未知或已完成的请求 id 直接忽略。

curl -N https://your-host/mcp \
  -H 'Authorization: Bearer fdlp_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

也可以直接使用支持 Streamable HTTP 的客户端，例如 mcp-remote https://your-host/mcp --header "Authorization: Bearer fdlp_xxx"。

浏览器与 CORS：平台 /mcp 由 Origin 白名单保护（FDL_MCP_ALLOWED_ORIGINS），未配置时拒绝带 Origin 的浏览器请求，防止 DNS rebinding；非浏览器 MCP 客户端没有 CORS 需求。浏览器直连需通过反向代理到同源，或显式加入允许来源。

安全建议

智能体的权限等同于所用令牌对应用户的权限，按最小权限分配；自动化用「只读」令牌加短有效期，用完撤销。
不要把令牌贴进聊天、工单或代码仓库。
管理员可在「运维」>「平台日志」按「MCP工具调用」审计智能体的操作。