Blog/教程/

Claude Code 接入 SandBase MCP：配置与 12 次实测

Claude Code 接入 SandBase MCP 的官方做法：用开源 CLI 一条命令装好，再看 12 次无头实测，覆盖小红书、抖音和生图三个任务的工具调用、通过率、耗时和成本。

作者 Daniel Russo
Claude Code 接入 SandBase MCP 服务器教程封面

第一次无头跑，Claude Code 为了算 4 个中位数，用了 19 轮、408 秒。找接口其实很快，3 次工具调用就定位到了小红书笔记搜索；麻烦在后面：搜索结果有 100 KB 左右，Claude Code 把它存成了文件，而 agent 没有权限跑读文件需要的 Python，剩下十几轮基本都在和权限规则较劲。补上两条权限规则之后，同一个任务降到 7 轮、两分钟以内。

这篇讲 Claude Code 接入 SandBase MCP 的完整过程：官方安装命令、MCP 暴露了哪些工具、无头模式下怎么配权限，以及 12 次打分实测（3 个任务 × 每个 2 次 × Claude Sonnet 5.5 和 GPT-6 Luna 两个模型）的结果。适合已经在用 Claude Code、想让它直接查公开社媒数据或生图、又不想一个个接 API 的开发者。

先说结论

  • 官方路径是开源的 SandBase CLI：connect --client claude-code 只往 ~/.claude.json 写一条 stdio MCP 配置，凭证是单独的 CLI Login key，存在仅本人可读的文件里。Claude Code 随后能看到 6 个工具：sandbase_discover、sandbase_inspect、sandbase_run、sandbase_run_get、sandbase_runs、sandbase_account。
  • 2026-10-03 的 12 次打分运行里，Claude Sonnet 5.5 过了 5/6，GPT-6 Luna 过了 3/6。抖音粉丝对比两个模型都是 2/2。生图失败全是同一个原因：异步生图任务完成后，sandbase_run_get 只给状态和费用，不给图片 URL。
  • 按 SandBase 标价算模型 token，Sonnet 每次中位数 $0.29，Luna $0.008。Claude Code 自己报的 total_cost_usd 用的是它内置价格表，Luna 被高估了约 50 倍。
  • 无头运行要放行 6 个 SandBase 工具，再加 Read 和 Bash(python3:*)。24 次 sandbase_run 里有 11 次结果太大，没进上下文，被落成了文件。

官方安装到底做了什么

SandBase 在 Connect AI tools 文档页 写了流程：在控制台 Setup 里选客户端，跑安装命令，浏览器里确认授权，重启客户端，再发一个安全的工具请求验证。安装脚本本身很薄。我把当天线上的 https://sandbase.ai/install.sh 和早些时候存的副本 diff 过，内容一致；带 --client claude-code 时，它执行的就是 npx -y @sandbaseai/cli connect --client claude-code。

SandBase 文档 Connect AI tools 页面，显示快速开始步骤和 install.sh 命令格式 截图：SandBase 文档「Connect AI tools」页列出了五步接入流程和下文用到的 install.sh 命令格式（2026-10-03 截取）。

# Option 1: the installer from the SandBase docs (needs Node.js 20+)
curl -fsSL https://sandbase.ai/install.sh | sh -s -- --client claude-code

# Option 2: the pinned v0.1.17 GitHub release the CLI README recommends
npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz connect --client claude-code

有个版本细节要留意：2026-10-03 当天，npm 上 @sandbaseai/cli 的 latest 还是 0.1.14，GitHub release 已经是 v0.1.17（2026-08-19 发布）。安装脚本走 npm，所以装到的是 0.1.14。想要新版本、或者想校验包，CLI 安装说明 里有固定版本的 tarball 地址和 SHA-256。

GitHub 上 sandbaseai/cli 的 llms-install.md，显示环境要求和 v0.1.17 只读 catalog 命令 截图：CLI 安装说明列出了环境要求（Node.js 20、一次性授权用的浏览器）和固定到 v0.1.17 的命令（2026-10-03 截取）。

授权完成后，CLI 只在 ~/.claude.json 里加一条配置。我机器上是这样（路径是我本机的）：

{
  "mcpServers": {
    "sandbase": {
      "command": "node",
      "args": ["/Users/liyb/.sandbase/bin/sandbase-mcp-bridge.mjs", "--client", "claude-code"],
      "env": {"SANDBASE_CLI_MANAGED": "1"}
    }
  }
}

这个文件里没有 key。bridge 是个很小的 Node 脚本，从 ~/.sandbase/credentials.json（我这里权限是 0600）读凭证，把每条 MCP 消息转发到 https://api.sandbase.ai/v1/mcp。本机装的 bridge 和 v0.1.17 源码里的逐字节一致。官方没有给 claude mcp add 的一行命令，CLI 管理的这条配置就是支持路径，后面 doctor 和 unregister 也靠它识别。

先验证再用：

npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz doctor --client claude-code
claude mcp list

我这边 doctor 输出 claude-code: status=configured, mcp=configured, ...，claude mcp list 输出 sandbase: node .../sandbase-mcp-bridge.mjs --client claude-code - ✔ Connected。以后要撤掉，unregister --client claude-code 只删 SandBase 自己那条；文档还建议去 Developer → API Keys 吊销对应的 CLI Login key。

MCP 暴露了哪些工具

通过 bridge 调一次 tools/list，返回 6 个工具。注解（annotation）一并列出来，配权限时要看：

工具作用注解
sandbase_discover按 q、type、vendor、limit 搜模型和 API只读
sandbase_inspect看某个 name 的入参 schema、价格和 execute_as 模板只读
sandbase_run用 name 和 arguments 执行模型或 API破坏性、开放世界
sandbase_run_get按 run_id 查异步任务状态只读
sandbase_runs最近调用的模型、状态、费用只读
sandbase_account美元余额只读

真正花钱的只有 sandbase_run，写权限规则时重点盯它，其余都是免费查询。

三个任务和打分方式

我用的是 Claude Code 2.1.246 无头模式。每次运行一个全新临时目录，配一个独立的 CLAUDE_CONFIG_DIR，里面放 CLI 那条 MCP 配置的副本。Claude Code 自己的模型调用走 SandBase 的 Anthropic 兼容接口，这需要在 ANTHROPIC_AUTH_TOKEN 里放一把普通的 SandBase API key，和 bridge 用的 CLI Login key 是两回事。三个任务：

  1. 小红书：找笔记搜索接口，搜「防晒霜」（只搜第一页、只跑一次），报告笔记数、点赞/收藏/评论的中位数和视频笔记数，不许输出作者名和笔记正文。
  2. 抖音：找瑞幸咖啡和星巴克中国的官方账号，对比粉丝数。
  3. 生图：找生图模型，最多 inspect 三个，选单张低于 $0.05 的最便宜那个，生成一张白色陶瓷马克杯的方形产品图，异步就轮询，最后返回图片 URL。

每个 prompt 结尾都要求输出一行 JSON。小红书这条原文如下：

Use the SandBase MCP tools (sandbase_discover, sandbase_inspect, sandbase_run). Find a Xiaohongshu note-search endpoint, inspect it, then search notes for the keyword 防晒霜 (sunscreen), first page only, one run. From the notes returned, report the number of notes, median likes, median saves (collects), median comments, and the number of video notes. Do not include author names, note titles or note text in your answer. Finish with exactly one line of JSON: {"endpoint": "...", "run_id": "...", "notes": 0, "median_likes": 0, "median_saves": 0, "median_comments": 0, "video_notes": 0}

打分只看 Claude Code 当次拿到的原始工具结果，不用我事后重新调，因为搜索结果每次都在变。小红书：5 个数字要和我从该次 sandbase_run 结果重算的完全一致。抖音：两个粉丝数都必须出现在该次原始结果里，且对应的是不带后缀的品牌主账号。生图：返回的 URL 能下载成图片，且标价低于 $0.05。

结果

任务Claude Sonnet 5.5GPT-6 Luna
小红书中位数2/21/2
抖音粉丝2/22/2
生图1/20/2
合计5/63/6
轮数中位数（范围）7.5（7–18）12.5（5–15）
耗时中位数（范围）106 秒（72–328）83 秒（33–120）
每次模型成本（标价），中位数（范围）$0.29（$0.16–$0.40）$0.008（$0.004–$0.010）
6 次模型成本合计$1.65$0.046

抖音任务最干净。四次都用了 douyin/search/user-search-v2，其中三次还对每个账号调了 douyin/app-v3/user-profile。最慢的那次 Sonnet（18 轮、328 秒）把两次主页查询各跑了两遍，中间还翻了自己的调用记录。四次都选了品牌主账号，没有选官方旗舰店之类的子账号：瑞幸咖啡约 737 万粉丝，星巴克中国约 1156 万，比值 0.64。几分钟内的不同运行之间，粉丝数会差几十（星巴克中国在 11,558,093 到 11,558,116 之间）。主页接口的返回里两个账号都带企业认证字段，拿它判断「是不是官方号」比对名字靠谱。

小红书的中位数波动很大，因为搜索结果本身在变：三次通过的运行里，点赞中位数分别是 113.5、123、256。每次通过都和它自己的原始数据完全对得上，所以波动来自搜索，不是算错。两个模型的路子不一样：Sonnet 对落盘文件跑了两条 python3 -c，一条看结构、一条算数；Luna 通过的那次先 Read 了四次（参数不对，又撞上 25,000 token 的读取上限），一个 Python heredoc 还被 Claude Code 的命令检查拦了，最后一条普通的 python3 -c 才跑通。

Luna 没过的那次小红书，是个很小但真实的坑。sandbase_inspect 返回的 execute_as 模板长这样：{"name": "sandbase_run", "arguments": {"name": "<tool>", "arguments": {}}}。Luna 把这层嵌套原样塞进了 sandbase_run 的参数，接口收到的参数变成了 {"arguments": {...}, "name": ...}，直接报 MCP error -32000: capability call failed。它随后返回了一串 null，没有瞎编，这个失败方式倒是对的。

生图为什么三次翻车

四次生图里有三次选了 alibaba/z-image-exp0622（inspect 标价每张 $0.013）。它是异步的：sandbase_run 返回 pending 和一个 run id，agent 按要求用 sandbase_run_get 轮询。轮询结果变成 completed、也显示了费用，但始终没有 output 或 URL。事后我自己用同一个 id 调 sandbase_run_get，字段一样。CLI Login key 也访问不了 REST 的 GET /v1/run/{id}，返回 HTTP 403 insufficient_scope。结果就是每次扣了 $0.013，图却拿不回来。好在三次都没有编造 URL。

唯一成功的是一次 Sonnet，选了 $0.005 的 z-image/turbo。它在同一次 sandbase_run 里就返回了 completed，output 里直接是 PNG 的 URL，不用轮询。奇怪的是模型页上写的是 async：

SandBase 上 z-image/turbo 模型页，显示每次 $0.005 基础价格和 async 执行方式 截图：z-image/turbo 模型页标的是每次 $0.005、执行方式 async，但它在 MCP 里第一次响应就带回了图片（2026-10-03 截取；页面顶部当时有「API Free Week」横幅）。

在异步结果能通过 sandbase_run_get 拿回来之前，建议在 prompt 里让 agent 优先选「一次调用就出图」的模型，并且在看到 completed 却没有 output 时轮询一次就停。pending 响应里的 pollInterval 是 3000 毫秒。

实测记录（2026-10-03，UTC）

输入只有上面的「防晒霜」关键词、两个品牌名和一句通用产品图 prompt，没有私人账号。下面是 sandbase_run 的异步生图响应（run 5ccd3dc1-192e-49b2-b94b-784ab54752fb），除了重复 task id 的 _meta 键，其余完整保留：

{
  "model": "alibaba/z-image-exp0622",
  "output": null,
  "pollInterval": 3000,
  "prediction_id": "5ccd3dc1-192e-49b2-b94b-784ab54752fb",
  "status": "pending",
  "statusMessage": "async result is still running; poll the task result later",
  "status_code": 202,
  "taskId": "5ccd3dc1-192e-49b2-b94b-784ab54752fb",
  "tool_name": "sandbase_alibaba_z_image_exp0622",
  "type": "capability"
}

同一个 id 完成后的 sandbase_run_get（省略了一个上游模型标签键）：

{
  "cost": "0.013",
  "created_at": "2026-10-03T14:39:42Z",
  "model": "alibaba/z-image-exp0622",
  "run_id": "5ccd3dc1-192e-49b2-b94b-784ab54752fb",
  "status": "completed"
}

数据接口完成后的顶层键是 model、output（列表，第一项里是 data）、prediction_id、status、status_code、tool_name。这是我在 MCP 里看到的结构，和 REST /v1/api 的返回包装不同，请当作观察结果，不是文档承诺。小红书一页搜索结果约 106 KB，抖音主页接口是 143–150 KB。

SandBase 上 xiaohongshu/app-v2/search-notes 模型页，显示 Free 基础价格、sync 执行和 9 个入参 截图：xiaohongshu/app-v2/search-notes 模型页标的是 Free、sync、9 个入参，和运行中 sandbase_inspect 返回的 schema 一致（2026-10-03 截取）。

成本：Claude Code 报的数和 SandBase 实际标价

Claude Code 结果 JSON 里有 total_cost_usd，但这是它内置价格表算的，不是 SandBase 的账单。Sonnet 还算接近（6 次 $1.68，我按标价算 $1.65）；Luna 报了 $2.29，标价算只有 $0.046，因为它不认识这个模型，stderr 里会打 unrecognized_model。我的算法：取每次运行累计的 usage，输入 token 按模型卡单价，缓存写入按输入价 1.25 倍、缓存读取按 0.1 倍，两个倍率都来自模型卡。2026-10-03 GET https://api.sandbase.ai/v1/models/<id> 返回：Claude Sonnet 5.5 输入 $2/M、输出 $10/M；GPT-6 Luna $0.1/M、$0.5/M。这个接口要带同一把 SandBase API key（Bearer）；没有 key 的话，公开模型页上也能看到价格。/v1/messages 的 id 在 GET /v1/tasks/{id}/cost 里查不到，所以我没有逐次对账。

大头是缓存流量。Sonnet 6 次一共 198 万缓存读取、42.4 万缓存写入，输出才 1.87 万，主要是 Claude Code 的系统提示和工具定义每轮重读。轮数越多越贵：19 轮的试跑花了 $0.84，同一任务 7 轮的版本是 $0.18–$0.27。

MCP 这边，用到的数据接口（xiaohongshu/app-v2/search-notes、douyin/search/user-search-v2、douyin/app-v3/user-profile）当天 base_price 都是 0。试跑加 12 次打分运行，账户余额一共少了 $0.044：三张 $0.013 的异步图加一张 $0.005 的 turbo 图；sandbase_runs 列出的 20 次数据调用全是 $0。选 GPT-6 Luna 做便宜对照，是因为它在我们的模型分档实测里 51/51 全对，成本约为 GPT-6.1 Sol 的 1/20。这次它每次比 Sonnet 便宜约 35 倍，但轮数更多。查数够用；工具约定里一有坑，就不太稳。

自己跑一遍

下面就是我最后两次验证用的脚本（GPT-6 Luna 跑抖音 prompt：16 轮、88 秒、标价约 $0.01；Sonnet 跑小红书 prompt：12 轮、343 秒、$0.38）。前提是已经做过 connect；API key 从环境变量读，不落盘。

#!/usr/bin/env bash
# Run one Claude Code task headless with the SandBase MCP server, with the model routed through SandBase.
# Usage: SANDBASE_API_KEY=... ./run_with_sandbase_mcp.sh <sandbase-model-id> "<prompt>"
set -euo pipefail
MODEL="$1"; PROMPT="$2"
: "${SANDBASE_API_KEY:?set SANDBASE_API_KEY in the environment}"
BRIDGE="$HOME/.sandbase/bin/sandbase-mcp-bridge.mjs"  # written by: connect --client claude-code
[ -f "$BRIDGE" ] || { echo "Run the SandBase CLI connect step first." >&2; exit 1; }
CFG="$(mktemp -d)"   # isolated Claude Code config; your normal ~/.claude.json is not touched
WORK="$(mktemp -d)"  # throwaway working dir; the agent may run python3 here
trap 'rm -rf "$CFG" "$WORK"' EXIT
cat > "$CFG/.claude.json" <<EOF
{"mcpServers": {"sandbase": {"command": "node", "args": ["$BRIDGE", "--client", "claude-code"], "env": {"SANDBASE_CLI_MANAGED": "1"}}}}
EOF
ALLOWED="mcp__sandbase__sandbase_discover,mcp__sandbase__sandbase_inspect,mcp__sandbase__sandbase_run"
ALLOWED="$ALLOWED,mcp__sandbase__sandbase_run_get,mcp__sandbase__sandbase_runs,mcp__sandbase__sandbase_account"
ALLOWED="$ALLOWED,Read,Bash(python3:*)"  # large MCP results are saved to a file; this lets the agent parse it
cd "$WORK"
env -u ANTHROPIC_API_KEY CLAUDE_CONFIG_DIR="$CFG" \
  ANTHROPIC_BASE_URL="https://api.sandbase.ai" ANTHROPIC_AUTH_TOKEN="$SANDBASE_API_KEY" \
  ANTHROPIC_MODEL="$MODEL" ANTHROPIC_SMALL_FAST_MODEL="$MODEL" ANTHROPIC_DEFAULT_HAIKU_MODEL="$MODEL" \
  DISABLE_TELEMETRY=1 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude -p "$PROMPT" --model "$MODEL" --output-format json --max-turns 30 \
    --allowedTools "$ALLOWED" > "$CFG/result.json"
python3 - "$CFG/result.json" <<'PY'
import json, sys
r = json.load(open(sys.argv[1]))
keys = ("subtype", "is_error", "num_turns", "duration_ms", "total_cost_usd", "usage")
print(json.dumps({k: r.get(k) for k in keys}, indent=1))
print(r.get("result"))
PY

Luna 那次打印的摘要如下。省略了 usage 里的其他键（output_tokens_details、server_tool_use、service_tier、cache_creation、inference_geo、iterations、speed）和最后的答案行；total_cost_usd 是 Claude Code 自己算的，不是 SandBase 的：

{
 "subtype": "success",
 "is_error": false,
 "num_turns": 16,
 "duration_ms": 87751,
 "total_cost_usd": 0.5171187500000001,
 "usage": {
  "input_tokens": 1872,
  "cache_creation_input_tokens": 58295,
  "cache_read_input_tokens": 203130,
  "output_tokens": 1674
 }
}

如果你的 Claude Code 用的是自己的 Anthropic 登录，就不需要那些 ANTHROPIC_* 变量，也不需要隔离配置：connect 之后 MCP 配置已经在 ~/.claude.json 里了。这条路径我没测，本文所有运行都走 SandBase 托管的模型。接口细节见 search-notes API 参考；想让模型也走 SandBase，可以申请一把 SandBase API key。

踩过的坑

  • 第一轮 MCP 还没就绪。 无头模式下 MCP 服务器启动时是 pending，12 次里有 10 次模型第一步调的是 Claude Code 的 WaitForMcpServers。多一轮，但没导致失败。
  • 大结果会落盘。 24 次 sandbase_run 有 11 次被存成文件，上下文里只剩一个指针。只放行 MCP 工具时，试跑尝试了 12 次 Bash，6 次被拒（普通 grep 算只读，能过）。放行 Read 和 Bash(python3:*) 就好了；不过 Claude Code 仍会拦部分 heredoc 和 shell 展开，单条 python3 -c 更容易通过。
  • sandbase_discover 是关键词匹配，不懂意图。 Luna 的 15 次 discover 有 9 次返回 count: 0，都是长句自然语言、中文查询，或者 vendor 过滤配长查询。“xiaohongshu note search”、“douyin” 这种短词就能搜到。Sonnet 8 次里只有 1 次为空。
  • 照抄 execute_as 会把调用搞坏。 接口参数直接放进 arguments，别再套一层。
  • 异步任务暂时拿不到结果。 见上面生图一节。

安全

  • 两把 key，两种权限。 bridge 用的 CLI Login key 权限范围是 mcp:invoke，我试过的 REST 接口都返回 403。泄露了影响面也有限。路由模型用的是普通 API key：像脚本里那样放环境变量，别写进 .claude.json、脚本或 shell 历史。
  • 权限规则就是你的花费上限。 sandbase_run 能调付费模型。交互式会话里让它保持「询问」；无头运行只放行任务需要的工具，--max-turns 设小，批量跑之前先看 sandbase_account。
  • Bash(python3:*) 等于任意代码。 只在脚本那样的一次性目录里用。我全程没用 --dangerously-skip-permissions。
  • 数据边界。 数据工具只读公开数据，需要 SandBase 账号；SandBase 不是小红书或抖音的官方合作方；不涉及私人账号、私信、创作者后台数据或任何账号操作。我在 prompt 里要求不输出作者名和笔记正文，本文也只给聚合数和品牌账号。

FAQ

SandBase 有官方的 Claude Code MCP 吗？

有。SandBase 文档和开源仓库 sandbaseai/cli 都写了 connect --client claude-code。它装一个本地 stdio bridge，连到 SandBase 的远程 MCP 端点；这个端点在官方 MCP Registry 里登记为 io.github.sandbaseai/cli。

Claude Code 配置里要放 SandBase API key 吗？

不用。CLI 把自己的 CLI Login key 存在 ~/.sandbase/credentials.json，~/.claude.json 里只有启动命令。只有当你还想让 Claude Code 的模型走 SandBase 时，才需要另一把 API key，而且应该放环境变量。

数据任务用哪个模型驱动 Claude Code？

这 12 次里，Claude Sonnet 5.5 过了 5/6，每次中位数 $0.29；GPT-6 Luna 过了 3/6，每次 $0.008。Luna 做简单查询没问题（抖音 2/2），遇到绕的工具模板就容易出错。每个任务只跑了 2 次，只能看方向，别当排名。

生图为什么拿不到图？

我这边，异步生图模型先返回 pending，sandbase_run_get 后来变成 completed 并带费用，但没有 URL。第一次 sandbase_run 就完成的模型（z-image/turbo，$0.005）会直接返回 URL。

一个任务大概花多少钱？

这里用的数据接口 2026-10-03 标价 Free，花钱的是模型 token：按标价 Sonnet 每次 $0.16–$0.40，Luna 每次不到 $0.01。Claude Code 自己的成本数对非 Anthropic 模型不准，要用 usage 自己算。

局限

测试范围说在前面：一天、Claude Code 2.1.246、CLI bridge v0.1.17、两个模型、三个任务，每个任务打分 2 次，外加 1 次试跑和 2 次脚本验证。12 次能暴露失败模式，算不出可靠的通过率。没测 Anthropic 订阅登录、交互式会话、其他生图模型和 Windows。Claude Code 本身的全貌可以看 Claude Code 完整指南；CLI 支持的另外 24 个客户端，见 SandBase CLI MCP bridge 一文。方法、prompt、打分规则和聚合结果都在本文里；原始对话记录含第三方帖子内容，只在内部保存。