通过 MCP 连接

D2B 的 MCP 服务器位于 https://d2b.dev/mcp/(Streamable HTTP)。认证有两种:宿主的登录(OAuth 2.1,在浏览器中批准,宿主自动续期 1 小时令牌)或 PAT 的 Bearer 头。工具与 REST / CLI / SDK 是同一套接口,每个工具都带类型化 schema 供工具调用(宿主的工具列表始终是最新的)。

规范由服务器下发

连接时,初始化响应中的 instructions 包含运行规范(用哪个工具、何时用,文件按引用导入,派生用 transform,遇到 409 重新读取,在节点处 commit_snapshot,用 delete_workbook 清理 ……)。若宿主截断 instructions,同样的文本可作为资源 d2b://guide 读取。仓库里只需要连接方式和路径选择(从编码智能体使用 D2B)。

工作区的创建也可以通过 MCP 完成(provision_workspace / delete_workspace;需要具备 workspaces:create / workspaces:delete 范围的整账户密钥;固定到某个工作区的密钥无法创建同级工作区)。

登录(OAuth)

只需登记 URL:宿主从 https://d2b.dev/mcp/ 的 401 发现授权服务器,并在浏览器中打开 D2B 的同意页面。页面显示应用名称、返回的宿主、授予的权限(workbooks 的 read / write / delete 以及 cloud-files:read),以及以哪个账户运行(默认账户或你的某个开发者账户),确认后批准。访问令牌有效 1 小时,宿主用刷新令牌续期。它会以 oauth:<应用名> 出现在控制台的 设置 > 令牌 中,因此可按连接逐个吊销。

应用名称由宿主自行申报,D2B 不作验证。遇到意料之外的同意页面请拒绝。宿主不支持 OAuth,或 CI 之类的无人环境,继续使用 PAT 的 Bearer 头。

按宿主设置

claude mcp add d2b --transport http https://d2b.dev/mcp/

不带头登记时,首次使用会要求登录。无人环境改为传 PAT:

claude mcp add d2b --transport http https://d2b.dev/mcp/ \
  --header "Authorization: Bearer $D2B_PAT"

~/.cursor/mcp.json(或项目的 .cursor/mcp.json)。只写 URL,Cursor 会提示登录;要固定 PAT 则加上 headers:

{
  "mcpServers": {
    "d2b": {
      "url": "https://d2b.dev/mcp/",
      "headers": { "Authorization": "Bearer d2b_pat_..." }
    }
  }
}

.vscode/mcp.json。只写 URL,VS Code 会提示登录(PAT 则加上 headers):

{
  "servers": {
    "d2b": {
      "type": "http",
      "url": "https://d2b.dev/mcp/",
      "headers": { "Authorization": "Bearer ${input:d2b_pat}" }
    }
  },
  "inputs": [{ "id": "d2b_pat", "type": "promptString", "password": true, "description": "D2B PAT" }]
}

在 Settings → Connectors → Add custom connector 登记 https://d2b.dev/mcp/。认证保持默认的**「立即登录」**即可(浏览器会打开 D2B 的同意页面)。要用 PAT 连接,选择「不登录」并在请求头中设置 Authorization: Bearer d2b_pat_...。两者都不支持的版本请经由 mcp-remote:

{
  "mcpServers": {
    "d2b": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://d2b.dev/mcp/",
               "--header", "Authorization: Bearer d2b_pat_..."]
    }
  }
}

若使用 PAT,建议使用限定到 workbook 并带速率上限的最小权限令牌(快速开始 §1)。

工具地图

目的	工具
发现	`list_my_data` / `get_schema`(`include_json_schema`) / `profile_table` / `get_lineage` / `get_downstream` / `search`
读取	`read_table` / `query_sql` / `validate_sql`
核查	`review_table` / `review_workbook`(有依据的问题:源文件的公式、表的不变量、标签与定义是否一致;`mode="agent"` 返回作业,用 `get_job` 等待)
导入数据(引用优先)	`ingest_url` / `request_upload` → `ingest_upload` / `list_cloud_files` → `import_cloud_file` / `track_onedrive_file` / `ingest_file`
检查结构 / 保留原件的 revise	`analyze_source` / `get_parse_spec` / `update_parse_spec` / `materialize_source` / `revise_source`
容器(工作簿、工作区)	`list_my_workspaces` / `create_workbook` / `delete_workbook` / `provision_workspace` / `delete_workspace`
创建与修正	`create_table` / `add_transform` / `list_transforms` / `upsert_rows` / `delete_rows` / `write_a1` / `put_sheet` / `get_sheet` / `list_sheets`
模式	`add_column` / `rename_column` / `retype_column` / `drop_column` / `rename_table`
公式与说明	`set_formula_column` / `list_formula_columns` / `clear_formula_column` / `set_artifact_description` / `set_column_description` / `set_table_style` / `get_table_style`
历史	`list_snapshots` / `commit_snapshot` / `restore_snapshot` / `diff_snapshots` / `recompute_stale` / `list_ops` / `undo_op`
冲突、同步、交付	`list_conflicts` / `resolve_conflict` / `export_tables` / `bind_external_sheet` / `list_sync_bindings` / `unbind_external_sheet` / `list_file_links` / `sync_file_link`

类型

工具输入是严格类型化的(枚举 / 结构化模型;harness 可在生成时拒绝非法值)。唯一依赖数据、无法静态类型化的 upsert_rows.rows,可用 get_schema(name, include_json_schema=true) 返回的「该表一行的 JSON Schema」在运行时约束。

错误使用与 REST 相同的 problem+json 词汇(带 suggested_fix)— 阅读错误。

传输是无状态的 streamable HTTP — 服务器不保存会话,每个请求自包含(对重试和水平扩展安全)。