从MCP到CLI：AI Agent工具接口的工程选型与踩坑实录

最近几个月被同一个问题反复问了好多遍“你们的 Agent 也是用 CLI 接的MCP 不用了吗”答案是很多地方确实不用了至少不再把 MCP 当默认选项。我接触的几个团队从内部工具到跨平台系统都陆陆续续把原来按 MCP 标准开发的工具接口拆掉换回了一套朴实无华的命令行接口。不是 MCP 不好而是在真实工程场景里CLI 的性价比高得惊人。这篇文章不站队只把我看到的、踩过的、测试过的细节摊开讲清楚MCP 到底贵在哪CLI 到底简单在哪以及什么时候你应该咬牙继续用 MCP什么时候赶紧切 CLI。1. 先搞清楚MCP 和 CLI 到底在解决什么问题1.1 MCP 是被设计出来的“标准接口”MCPModel Context Protocol是某头部 AI 公司公开的一整套开放协议目标是给 AI 模型和外部工具、数据源之间定一个统一“插座”。在没有它之前模型接一个数据库要写一套接口接一个文档库又要写一套每个工具都有自己的调用方式和鉴权逻辑模型侧的适配成本非常高。MCP 的想法很直接所有工具都按照同一套 JSON-RPC 2.0 规范暴露能力模型端只需要一个客户端就能看懂所有服务端的工具。具体到技术实现MCP 包含几个核心概念client 和 serverserver 通过 transport 提供服务transport 常见的有 stdio 和 HTTP(S)服务端要声明 tool每个 tool 用 JSON Schema 描述入参调用流程是 initialize 握手然后 tools/list 获取工具列表再 tools/call 执行具体调用。此外还有 resources可动态发现的资源和 prompts提示模板这些扩展能力。你可以把 MCP 理解成“AI 世界的 USB-C”设备厂商只要做一根符合标准的线任何充电头都能用。这个愿景本身没有问题而且在某些场景下确实好用。问题出在“标准”的落地成本远比宣传材料里写的高。1.2 CLI 是早就存在的“天然接口”CLI命令行接口不是什么新鲜事物但把它当成 AI 工具接口来用是这两年一个非常实际的回归。Unix 哲学早就定下规矩每个程序做好一件事用文本流把小程序组合成复杂系统。对 Agent 来说一个 CLI 程序就是一个完美的函数参数通过命令行传进去结果从 stdout 输出成功失败看 exit code日志从 stderr 走。你甚至可以定一个极其简单的约定CLI 只输出 JSON。Agent 侧用 subprocess 调命令捕获 stdoutjson.loads解析然后该干嘛干嘛。没有握手没有 schema 协商没有 transport 层没有 SDK 版本兼容问题。LLM 本身就是被海量命令行文本训练出来的让它看懂--help输出、照着示例拼一个命令往往比让它理解一堆 JSON Schema 定义再生成一次符合条件的 tool call 更容易。这里有个关键认知对模型来说调用一个 MCP tool 和调用一个 CLI 命令本质都是“文本进、文本出”。区别在于 MCP 在中间加了一整套协议层和生命周期管理而 CLI 把这一切简化成了进程调用。省掉的那部分恰恰是工程上最容易出问题的部分。2. 大厂转向 CLI 的三个真实原因我前阵子问了一圈做 AI 基建的朋友大家的答案惊人一致不是 MCP 烂是它对我们这个场景来说太贵了。贵在维护成本贵在调试成本贵在权限控制的复杂度。2.1 复杂度失控一个“查天气”变成了一个“微服务”这是最核心的原因。为了让模型能调用一个内部数据查询工具你需要做的事情包括引入 MCP SDK初始化 server写 tool 的 JSON Schema处理 initialize 握手和能力协商处理 transportstdio 模式调试困难HTTP 模式要管理端点和鉴权还要时刻跟进客户端 SDK 的版本变更因为客户端一升级服务端可能就得跟着调。我见过一个内部 BI 工具的接入过程原本是一段几百行的查询脚本为了套 MCP团队花了两天时间写了连接层、schema 定义和错误映射最后发现问题出在 client 端 SDK 版本和 server 端能力声明不匹配。同样的功能如果直接把这个脚本包成一个 CLI 函数最多一个小时就能跑通。我拿生活中的例子类比MCP 相当于你要开一家餐厅所以需要把桌布、菜单、上菜流程、服务员制服全部标准化CLI 相当于直接递给你一个打包盒虽然卖相朴素但顾客立刻就能吃上饭。当你的目标是快速让模型具备某个能力时标准化流程带来的负担远大于收益。2.2 调试地狱每多一层封装就多一群背锅位MCP 在 stdio 模式下调试极其难受。client 和 server 之间的通信本来就在标准输入输出上跑你在控制台里执行命令时根本看不到它们之间到底交换了什么。出了问题你得怀疑 schema 定义是不是有误JSON-RPC 序列化有没有失败initialize 是不是还没完成timeout 设置是不是太短。每一层都可能是凶手每一层都得单独排查。CLI 方案就完全不一样。我在终端里手动执行一次命令看 stdout 是不是预期输出看 stderr 有没有报错看 exit code 是不是 0——三步就能完成定位。就算模型调用的姿势不对我也能在自己的环境里复现相同命令问题是在参数解析、脚本逻辑还是权限缺失一眼便知。HTTP transport 模式也好不到哪里去还要额外处理鉴权、CORS、回调地址这些和工具本身的功能毫无关系纯粹是协议层强迫你承担的复杂度。而 CLI 天然继承操作系统的能力和调试手段这就是“少一层比多一层强”的典型体现。2.3 安全边界CLI 可以甩锅给操作系统LLM 调用工具的核心担忧是权限失控。MCP 的 tool 一旦注册客户端可以在任何上下文里调用权限控制需要你自己在 server 内部实现比如判断请求来源、维护 allowlist、检查参数范围。这些代码写起来不难但很容易漏而且很难审计。CLI 可以直接依赖操作系统的安全模型。文件系统权限、用户组、sudo 规则、容器隔离、企业现有的安全策略全部可以直接套用。审计痕迹也能直接用系统级日志来记录不需要自己在脚本里打一份。对一个追求稳定和合规的团队来说这一点几乎可以直接决定选型方向。3. 实操对比同一个工具两条路各写一遍光讲概念太虚我拿一个最常见不过的模拟项目 X——内部知识库检索加摘要工具——把两条路的实现细节摊开给你们看。3.1 任务定义输入两个参数query 字符串返回几条结果top_k控制返回数量。输出检索到的文档片段和基于这些片段生成的摘要。功能简单但足够体现两种方案的工程成本差异。3.2 MCP 实现Server、Schema、握手全都要基于某个官方 Python SDK 的简化示例思路和官方文档一致代码只保留最关键路径import json from mcp.server import Server # 官方SDK的server基类 from mcp.types import Tool, TextContent app Server(kb-search) app.list_tools() async def list_tools(): return [ Tool( namekb_search, description检索知识库并返回摘要, inputSchema{ type: object, properties: { query: {type: string, description: 查询词}, top_k: {type: integer, default: 5} }, required: [query] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name ! kb_search: raise ValueError(fUnknown tool: {name}) query arguments[query] top_k arguments.get(top_k, 5) results search_kb(query, top_k) # 原本的查询逻辑 summary summarize(results) return [TextContent(typetext, textsummary)]这段代码光看主体并不算多但你在真实项目中要处理的远不止这些server 实例的启动方式、stdio transport 的初始化、异常时的错误结构体、超大返回值的分片策略。而且只要客户端和 SDK 有版本调整这段代码就可能需要重新适配。3.3 CLI 实现argparse 加 JSON完事同样的功能CLI 版本就是一个标准 Python 脚本#!/usr/bin/env python3 kb_search.py - 知识库检索工具Agent 版本 import argparse import json import sys def main(): parser argparse.ArgumentParser(descriptionKnowledge base search with summary) parser.add_argument(--query, requiredTrue, help查询词) parser.add_argument(--top-k, typeint, default5, help返回结果数量) parser.add_argument(--format, choices[json, text], defaultjson, help输出格式Agent 请使用 json) args parser.parse_args() try: results search_kb(args.query, args.top_k) summary summarize(results) if args.format json: # stdout 只输出 JSON日志全部走 stderr print(json.dumps({ ok: True, summary: summary, results: results }, ensure_asciiFalse)) else: print(summary) except Exception as e: # 错误信息走 stderr同时用非零退出码标记失败 print(json.dumps({ok: False, error: str(e)})) sys.exit(1) if __name__ __main__: main()配合一个给 Agent 用的 system prompt 约定“调用 kb_search.py 时必须传 --query建议传 --top-kstdout 只会输出一个 JSON 对象命令执行失败时 exit code 非零错误信息在 stderr。”就这么多Agent 就能用得明明白白。3.4 关键差距开发成本、调试体验和模型友好度把两条实现路线放在同一个表格里看差距非常直观对比项MCP 方案CLI 方案代码量工具逻辑之外还要写 server、schema、transport工具逻辑之外只有 argparse 和 JSON 输出调试方式需 mock client、抓协议日志、排查握手终端手动执行一次看输出即可协议依赖依赖 SDK 版本升级可能带来兼容问题无协议依赖脚本即接口权限控制需在 server 内自研鉴权和审计复用系统用户、sudo、容器隔离模型友好度模型要理解 tool schema 并生成结构化调用模型对命令行参数天然更熟悉延迟上也有差异。MCP 即使走 stdio一次工具调用也要先完成初始化握手再执行调用如果 server 每次冷启动这个开销会叠加。CLI 本质是一次进程调用启动和解析的开销通常比协议握手小得多。MCP server 能常驻进程在大量连续调用的场景下反而更快但代价是你要维护一个常驻服务状态管理、连接回收、并发处理全是新问题。4. 技术选型什么时候继续用 MCP什么时候切 CLI别从一个极端跳到另一个极端。我的判断标准非常简单先看你是“佛系调用”还是“需要协议能力”。4.1 无脑选 CLI 的场景如果你的工具满足下面任意几点CLI 就是更省力的方案工具本身已经有命令行或脚本实现比如数据库查询、HTTP 请求、文件处理、云平台操作。云平台通常自带 CLI加一个--format json输出模式就完事。调用是无状态的每次调用自包含不依赖之前的对话或会话状态。团队迭代速度快需要今天定义接口、明天就让模型能调用。CLI 改完参数马上生效MCP 改完还要重新走一遍 server 发布。你能完全控制输出格式。自己写的脚本想输出什么 JSON 结构都行。我实际经历的大部分内部工具都符合这些条件所以它们迁移后的体感是“整个世界清静了”。4.2 继续用 MCP 的场景下面这些情况CLI 反而会非常别扭MCP 才是正确选择工具需要动态发现资源比如 IDE 插件要实时感知项目文件列表或者需要让模型发现自己“现在能拿到什么数据”。MCP 的 resources 机制是专为这种场景设计的CLI 很难优雅表达。需要双工通信或长连接服务端要主动向客户端推送状态变化而不是模型每次来拉取。CLI 本质上是一问一答。需要跨团队、跨组织共享工具生态目标是一套接入被很多方复用。此时 MCP 的标准化价值才能真正体现。需要 server 端维护复杂的上下文状态比如一个长期运行的代码库索引服务所有查询都基于同一份内存索引。MCP 常驻进程比 CLI 每次冷启动重建索引要合理得多。4.3 我当时是怎么决策的我给自己定过一个非常实用的筛选表按优先级判断优先级判断条件结论1已有现成 CLI 或脚本是默认选 CLI2需要动态资源发现或长连接是选 MCP3需要跨团队生态复用是选 MCP但先评估维护成本4状态放在 server 内存里是选 MCP5其余情况选 CLI这套判断逻辑帮我避免了不少过度设计。很多时候大家想上 MCP只是因为它是“新标准”、看起来更有前瞻性但工程里最值钱的永远是可维护性。5. 踩坑实录从 MCP 迁到 CLI 时的常见问题迁移本身不难但一定会踩几个典型的坑。我把这些坑和对应的解法整理成速查表基本覆盖了我在好几个项目里翻过车的地方。5.1 stdout 被污染JSON 解析直接崩最常见的问题没有之一。很多脚本作者习惯在结果前后打印提示信息比如“正在查询...”“查询完成共 5 条结果”。这些内容如果出现在 stdout 上Agent 端json.loads就会直接抛异常。模型拿到一个解析不了的输出要么重试要么报错整个链路就断了。解决方法是把约定写死stdout 永远只输出一个 JSON 对象日志全部走 stderr。脚本内部就算要打印调试信息也统一用logging模块打到 stderr。再激进一点在脚本最后加一个“输出校验”判断 stdout 是不是只有一个合法 JSON不合法就直接报内部错误。这个“自检”步骤看起来很笨但真的能救你一命。5.2 长任务超时Agent 等不起Agent 框架里对工具调用通常有时长限制可能是 30 秒也可能是 60 秒。CLI 命令一旦跑一个慢 SQL 或拉一批跨网络的数据很容易超时。这时候光靠 CLI 同步执行就不行了。我习惯的模式是把长任务拆成两个命令一个命令负责提交任务并立即返回任务 ID另一个命令负责查询任务状态和结果。第一个命令把任务丢到后台队列或者写个临时文件第二个命令轮询读取。对 Agent 来说它先调用 start_task再反复调用 get_task_status直到拿到 done。这种“命令组合”思想在 CLI 世界非常自然而在 MCP 里你需要写两个 tool 外加一套状态管理复杂度完全不在一个量级。5.3 参数注入和 shell 拼写陷阱CLI 毕竟是命令字符串拼接一不留神就会出问题。如果 Agent 生成的 query 里包含特殊字符比如分号、管道符、双引号直接拼进 shell 命令里可能产生意料之外的行为。两条铁律必须遵守。第一在 Python 里用subprocess.run([...])列表形式传参绝对不要自己拼一串命令再丢给shellTrue。列表传参能避免绝大多数 shell 注入问题。第二参数要做白名单和格式校验。比如 top_k 必须是 1 到 50 的整数query 的最大长度限制住输出内容的大小上限也限制住防止模型从一个合法参数里绕出不该有的权限。5.4 权限模型Agent 跑在哪个用户下Agent 服务通常跑在一个固定的系统用户下。如果这个用户权限太大一次误调用可能造成不可控影响权限太小需要特权操作的命令又会频繁失败。我之前碰到一个项目Agent 要查询内部元数据平台但那个平台只允许特定管理员账号访问普通服务账号根本没有权限。当时的做法是设计了一个受控的高权限 helper 命令普通 Agent 进程没有直接执行高权限命令的权限而是把请求转发给一个独立的受信任进程由它在 sudoers 白名单范围内执行。这个方案在 CLI 世界里实现非常直接因为你可以用系统底层的权限机制来约束而不用在应用层手写一套权限控制逻辑。5.5 模型忘了加 --format json另一个看起来很荒谬但实际经常发生的问题你在 system prompt 里写了命令必须加--format json但模型就是会漏掉特别当它模仿历史示例时可能把不带参数的版本学进来。一旦漏了Agent 拿到的是人类可读文本解析逻辑立刻崩。我的应对方式是给 Agent 单独封装一个入口脚本不暴露全部参数只暴露 Agent 必须使用的几个参数并强制在脚本内部固定输出 JSON人类用的大而全参数完全不透出给模型。这样一来模型根本没有机会忘掉--format json因为它已经写死在脚本里了。6. 我的建议先 CLI 跑通再按需升级 MCP从这几个项目的经验里我总结出一个现在一直在用的模式“能 CLI 就 CLI需要动态能力再上 MCP。”先把工具用最简单的命令行接口接进 Agent端到端跑通验证模型真的能用到它、产出正确结果。只有当需求明确指向 MCP 的独特能力时——动态资源发现、长连接、跨团队生态复用——再针对性地上 MCP。至少在我的经验里超过八成场景根本走不到那一步CLI 就已经完全够用而且维护十分省心。还有一个非常实用的小技巧如果手头的 CLI 还没有 JSON 输出模式别急着重写整个脚本。在入口加一个--json分支把现有逻辑的输出重构成一个字典再json.dumps或者用一个 shell 包装脚本把输出包成 JSON。先让链路跑通再逐步把参数收敛成 Agent 友好的接口。你会发现真正花在接入上的时间可能只要一两个小时。协议本身无所谓好坏工程上要选择的永远是那个更便宜、更可控、更好调试的接口。CLI 在最朴素的意义上依然是最好的 Agent 工具接口之一这大概也是它在这一轮技术淘汰赛里活下来的真正原因。