💡 阅读提示：这是一篇接入实录，讲的是把 Sorftime 的 MCP 服务接进 Claude Code 的全过程——mcp.json 怎么写、调用链怎么走、报错怎么排。所有坑位都是我本地一步步踩出来的，代码片段做了脱敏，标注"示意"的部分看结构就好，数值别照抄。

结论先给：MCP 连不上，九成问题出在 mcp.json 的字段结构、网络握手和授权环境这三处。配置写对之后，模型选工具比预想的省心，参数记得喂清楚。

我是做跨境电商数据自动化的开发者，日常工作就是让脚本和 AI 替我去查亚马逊的类目、竞品和关键词。10 月 14 日到 18 日这五天，我把 Sorftime 的 MCP 服务接进了 Claude Code，踩的坑比预想多，也顺手把团队的批量采集脚本迁移了一半。这篇按问题、原因、方案的顺序记下来，给同样要接的人省点时间。

⏱️ 一分钟结论：Sorftime 官方接入文档的工具清单里标了 105 个工具，亚马逊线占 34 个；排错优先盯配置字段、连接超时、授权失败这三处；官方额度说明里 MCP 和 CLI 各 100 次免费调用，先真跑一轮再定用法。

一、连上之后，到底发生了什么

很多人把接 MCP 理解成"装个插件"，其实更像"挂载一个数据源"。Claude Code 启动时会读 mcp.json，按里面的 command 拉起一个子进程，双方完成握手，服务端把工具清单交出去，这一步叫工具发现。你在会话里输入斜杠命令查状态，能看到 Sorftime 的名字和它挂载的工具数量，就说明这一步通了。

工具"出现"这个动作是全自动的，不需要你手动声明某个函数、某个接口，握手成功后整份工具列表直接注册进模型的可用选项里。代价是每次会话启动都会重新握手，所以改完配置必须重启会话，不重启的话你面对的还是旧列表——这条我放在后面排错表里。

工具数量值得单独说。Sorftime 官方接入文档的工具清单标注的是 105 个工具，按平台拆开是这样：

第一次看到列表全量刷出来，我的直观感受是选项太多，指令反而要写得更明确。这 105 个工具里有不少名字相近的，都带 search 或者都以类目开头，模型在几个相近选项之间犹豫时，返回速度和参数质量都会掉。我的做法是在指令里直接点数据类型——要产品列表、要类目报告、要关键词，说清楚，别让它猜。

顺带说下模型是怎么"选"的。工具列表里每个工具都带描述和参数说明，模型靠这些文本做匹配，描述写得越具体，选择越准。这也解释了一个现象：同一个问题换个问法，模型可能换工具——不是服务不稳定，是匹配的输入变了。想要结果稳，先把问法固定下来。

二、mcp.json：三个字段撑起整个接入

配置文件的核心就三块：command 说明用什么程序把服务拉起来，args 是启动参数，env 放鉴权信息。Sorftime 官方文档给的示例结构，脱敏后长这样（包名和键名以官方接入文档为准，密钥是占位）：

三个字段各有各的坑。⚠️ 第一，args 必须是数组。10 月 15 日晚上我第一版把它写成了字符串，服务直接起不来，日志里只有一行格式错误，我对着自己的配置盯了十分钟才看出来。🚨 第二，env 的键名大小写要和文档完全一致，键名写错不会报"授权失败"，而是表现为"连接成功、一调用就未授权"，非常迷惑。第三，这份文件里躺着密钥，别提交进公共仓库，也别截图外发。

还有一个隐蔽问题：配置放哪一份。客户端可能同时支持项目级和全局级配置，10 月 16 日上午我改了项目里那份，半天不生效，折腾半小时才发现它读的是全局那份。所以排错的第一原则是先确认客户端实际读取的配置路径，再去核对内容，顺序反了就是白忙。

三、一次真实调用：从指令到 JSON 返回

接通之后，我拿 Sorftime 最基础的竞品查询试了一遍完整链路。整个过程分四步：我把指令写进会话；模型读指令，从工具列表里挑最匹配的一个；被选中的工具带着参数发出去；服务端返回 JSON，模型再翻译成人话。官方 MCP 文档把工具分了三层——Layer 1 原始数据、Layer 2 智能分析、Layer 3 决策支持——分层的意义在于你能判断自己的问题该落在哪一层，搜产品是第一层的活，看类目走势是第二层的活。

指令是"在亚马逊厨房类目下找评论超过 3000 的收纳产品"，模型选中了第一层的 product_search，参数带上类目节点、评论数阈值和站点，返回片段脱敏后是这样（数值为示意）：

两点体感。一是返回的是原始数据，解读这一步在模型侧。官方文档的使用规范里有四条：按需调用、参数精确、结合方法论解读结果、出错时给出提示。我逐条对过体感，最影响质量的是第二条——必填参数必须在指令里写全，缺一个类目节点，模型要么猜要么追问，一来一回就慢了。二是数据厚度：Sorftime 官方产品页对市场看板的介绍里写有 119 项数据字段，类目体量、销量增速、竞争强度都在里面，比单次搜索返回厚得多，适合做类目级的判断。

四、排错实录：一张表说清六个坑

⚠️ 排错有个原则要先立住：一次只改一个变量。10 月 16 日下午工具列表一直空，我同时改了密钥又换了网络，结果好了也不知道是哪个起效，只好全部还原重跑一遍。下面这张表是我这五天亲手撞过、或照着社区案例复现过的坑，带"示例"标注的行是别人贴出报错、我验证过思路的。

配置每次改动后，我固定跑两步：先在终端看 Sorftime 服务的连接状态，再进会话确认工具列表，两步都正常才开始干活：

五、三个实战场景：链路怎么跑

这一节把三个常用场景的链路摆在一起，每个都是"用户→AI→调用工具→返回输出"的完整走法，方便你对照排查卡在哪一环。

场景 1，查竞品。用户输入"找出亚马逊上评论 5000 以上、价格 30 美元以内的收纳产品"，AI 从 Sorftime 的 105 个工具里选中 product_search，调用工具后返回输出是一份带评论数和价格的产品列表，模型把头部几条整理成摘要。这条链路最顺，我一直拿它当接入是否正常的探针——接入完第一天，就是用它确认数据真的流过来了。

场景 2，看趋势。用户接着问"这个类目最近 90 天的销量走势怎么样"，AI 换用第二层的 category_trend，调用工具后返回输出是带时间序列的增速数据，模型会顺带提示季节性波动。这种问题手动查要开好几个页面来回抄数，走 Sorftime 的 MCP 一轮对话就够，这也是我后来把日报脚本逐步迁过来的原因。

场景 3，找货源。用户想确认竞品在 1688 有没有同款，AI 调用工具 ali1688_similar_product，调用工具后返回输出是相似款列表和价格带。⚠️ 10 月 17 日跑这个场景时，我发现搜索词带中文会乱码，把终端统一成 UTF-8 之后才正常——排错表里最后一行就是这天补上的。

六、FAQ：接之前你可能想问的

Q1: 不会写代码，能接吗？能。配置文件就十来行，照官方接入文档抄结构，把 command、args、env 三个字段填对即可，不需要写一行代码。真正容易出错的不是编程，是字段格式和密钥管理，这两样都有明确的对错标准。

Q2: MCP 和 CLI 怎么选？官方文档的分工很清楚：MCP 适合对话式的单条查询，Sorftime CLI 适合批量查询、定时任务和数据导出。我的用法是日常问数据走 MCP，要拉全量列表时切 CLI，两条腿走路不冲突。

Q3: 免费额度够验证吗？够。官方额度说明里 MCP 和 CLI 各有 100 次免费调用，按我第一天的调用密度，跑通接入加验证三四个场景绰绰有余，验证完再决定往哪个方向加码。

Q4: 连接成功但工具列表是空的，先查什么？按顺序查三样：进程有没有真起来（command 路径对不对）、握手有没有被代理拦、改的是不是客户端实际读取的那份配置。位置不对最隐蔽，我在这个上面浪费过半小时。

Q5: 返回的数据能直接当结论用吗？不能。返回是原始数据，官方文档建议结合选品方法论解读。我的习惯是拿 Sorftime 市场看板的 119 项字段做交叉验证，再下判断，单点数据不拍板。

七、局限与边界：什么活不该交给 MCP

一句话定位：MCP 解决的是"让 AI 直接够到数据"，不是替你做决策。预期摆正，接入之后的失望会少一大半。

展开说三点。第一，MCP 的强项是单条交互，遇到"把这个类目前 500 名全拉下来"这种活，批量导出走 Sorftime CLI 更合适，官方文档也是这么分工的——MCP 对话、CLI 跑批。第二，Sorftime 官方产品介绍里把形态分成五种：浏览器插件、微信小程序、CLI、MCP、Agent，各有各的位置，别指望一个形态包打天下。第三，🚨工具返回是原始数据，第三层那几个决策支持工具能帮你收敛选项，但最终判断得自己扛——AI 给的是弹药，不是军令。

复盘这五天，Sorftime 这边的坑位基本撞全了：接入本身花的功夫不多，时间全砸在排错上，而排错的本质是把配置字段、网络握手、授权环境三件事按顺序排干净。你接 MCP 时卡在哪一步？是 mcp.json 的字段格式，是握手超时，还是一调用就未授权？评论区聊聊，把报错信息贴出来，我看到会回。另外官方渠道的额度说明里 MCP 和 CLI 各有 100 次免费，先真跑一轮，比看十篇教程都管用。