Tokeny 直连官方 MCP SDK:绕开 LangChain 框架,用工具可见性、权限门复核与命令安全审核管住能操控电脑的 Agent
核心结论:桌面 AI Agent 产品 Tokeny 在生产路径上没有经过 LangChain,而是直接使用官方@modelcontextprotocol/sdk接入 MCP 工具服务;工具经过 Native binding(原生绑定)和权限门(Permission Gate),再进入自研的 Agent Kernel 执行。这套设计要解决的不是 “能不能连上 MCP”,而是真接入一个能操作本地电脑的 Agent 后必须面对的四个问题:工具太多塞不进上下文、运行中目录变化带来的授权边界、服务报错时 Agent 该不该继续、以及 Shell 命令到底安不安全。Tokeny 对应的做法是:用四种工具可见方式控制模型看到什么,用 “本次 run 已授权集合” 冻结目录与 Schema,按 deny 优先顺序做权限复核,命令审核只允许模型读脚本、不允许模型跑脚本,并在执行前校验文件指纹。需要注意,可见性不等于权限,工作空间 roots 不是操作系统级沙箱,命令审核也不能替代对第三方 MCP 服务来源的审查;官方文档同时列出了 MCP Apps、Sampling、Elicitation、Prompts、Tasks 等尚未实现的能力。
一、架构背景:为什么直连官方 SDK
1. 接入链路
- 直连官方@modelcontextprotocol/sdk;
- Native binding 完成工具协议与本地执行层的对接;
- Permission Gate 权限门做准入与复核;
- 工具进入自研 Agent Kernel 调度执行;
- 生产路径中不引入 LangChain 作为中间框架。
2. 直连后要处理的典型问题
| 问题 | 说明 |
|---|---|
| 工具数量压力 | 一个服务可能有几百个工具,全部塞进请求,模型工具上限和 token 都扛不住 |
| 目录动态变化 | 运行到一半服务更新工具目录,新出现的工具算不算已授权 |
| 调用异常处理 | 服务返回 500、参数类型错误、断线或超时,Agent 该停下还是继续 |
| 命令安全判断 | 模型发起npm run build这类命令,是否允许在本机执行 |
二、工具可见性:四种方式管理模型能看到什么
在「插件 → 已安装」打开某个服务的工具列表,可以设置工具可见方式:
| 方式 | 配置值 | 行为 |
|---|---|---|
| 直接可用 | direct | 在模型请求里直接声明工具,仍受工具数量上限和权限约束 |
| 按需网关 | gateway | 模型先通过list_mcp_tools查目录,再用call_mcp_tool调用 |
| 搜索后加载 | deferred | 模型用search_mcp_tools搜索,下一轮拿到匹配工具的 Schema 后直接调用 |
| 隐藏 | hidden | 不提供该服务或工具的调用入口 |
1. 按工具单独覆盖
服务级设置可以用toolExposure按工具原名单独覆盖,例如把查询类工具设为direct,把删除类工具设为hidden。工具名必须精确匹配,不支持通配符。示例配置:
{
"exposure": "deferred",
"toolExposure": {
"lookup_record": "direct",
"delete_record": "hidden"
},
"connectionScope": "workspace"
}
2. 实现细节
- search_mcp_tools对名称、描述和服务说明做本地确定性排序,一次最多返回 8 项;
- 模型工具容量在装配时预留,超出容量时移除最早加载的工具,需要时再搜索一次可重新加载;
- 网关模式查询大服务时,如果完整列表超过工具输出预算,先返回名称索引和精确查询方法,分页用offset继续读;
- 隐藏和搜索加载只控制 “模型能看到什么”,不替代权限设置,实际调用仍要通过工作空间和 Agent 策略检查。
三、目录冻结:三个集合加每轮冻结
这是整个集成里边界最清楚的一环,Tokeny 区分三个集合:
- 服务当前工具目录:MCP 服务此刻对外暴露的工具;
- 本次 run 已授权集合:准入时冻结工具身份、Schema 和绑定;
- 本轮模型可见子集:从已授权集合中选出、本轮实际提供给模型的工具。
1. 流转关系
服务当前目录 ──run准入时冻结──▶ 本次run已授权集合
├── 搜索/直接声明 ──▶ 本轮模型可见子集(+ hash落盘)
└── 实际执行前再次复核启用状态/策略/权限
2. 冻结规则
- 搜索只能从已授权集合里选,运行期间新安装的服务或新出现的工具,不会被加进本次权限范围;
- 每个新的模型轮,可见子集和它的 hash 随输入一起冻结并写入 journal;
- 重试、接管和恢复都使用原来冻结的视图,恢复同一个 run 时还会恢复工具加载顺序,不会因重新搜索改变选择;
- 只有新的用户回合才重新搜索。
3. 目录刷新约束
- 分页读取完整 tools 目录,最多 100 页、10000 项;
- 遇到重复 cursor、任一页失败或超限,整次刷新失败,不发布部分结果;
- 收到tools/list_changed通知时合并并发刷新,客户端 generation 校验防止旧连接覆盖新目录;
- 已经失效的目录,不能靠本地 SQLite 保存的旧目录重新获得执行权限。
四、连接范围:每个工作空间可以独立
外部服务连接默认全局共享。选择 “每个工作空间独立” 后:
- 每个工作空间建立自己的连接;
- 服务看到的 root 固定为当前工作空间;
- stdio 进程也在该目录启动;
- 连接池键包含服务、工作空间、配置身份和 root,两个工作空间不共用带 roots 状态的客户端或工具目录;
- 闲置 5 分钟回收,最多保留 16 个工作空间连接;
- 配置变更、服务禁用、工作空间删除和应用退出都会关闭对应连接。
需要特别说明:roots 只是给服务的目录提示,不是操作系统沙箱,并不限制外部进程的系统权限,第三方 MCP 服务仍应先审查来源再安装。
五、调用失败:交还 Agent 决定,不中断整轮
1. 调用前参数校验
- 按目标工具当前inputSchema校验参数,支持 draft-07、2019-09 和 2020-12;
- 缺参数或类型错误时,返回 “未发起调用” 的工具错误,并附上顶层必填项、允许属性和类型提示;
- 参数保留原值,不做类型转换、不填默认值、不删除多余字段,避免 “帮模型改参数” 的隐蔽行为。
2. 异常归类
服务端 JSON-RPC 错误、HTTP 4xx/5xx、发送前失败、结果校验错误、断线和超时,统一作为工具失败返回给模型;错误诊断使用本次请求 ID 对应的实际响应,而不是只看异常类型。
3. 结果处理边界
- 失败结果正常持久化,但不代表服务端一定没有产生部分副作用;
- 之后是换方法、重试还是向用户报告,由 Agent 决定,MCP 层不会因结果未知就终止整轮;
- 长调用使用真实notifications/progress,最多每 150ms 投影一次进度;空闲超时和调用总时长可配置,用户停止时取消会传播到调用;
- isError、有序文本和图片、structuredContent保留到 receipt 和历史记录;二进制资源保存为工作空间 / 会话范围内附件,单个最多 32MiB,至少保留 7 天;PDF 只保证原始字节被保存,不代表已解析出文字。
六、权限复核:deny 永远优先
MCP 工具可见,不代表调用一定获准。Tokeny 权限评估顺序保证 deny 优先:
- 系统保护路径和不可绕过的危险命令,硬阻断;
- guardrail deny 和用户规则 deny;
- 安全审核的 deny /ask/allow;
- 工作空间权限模式;
- 规则匹配,需要时人工审批。
1. 三种工作空间模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 默认权限 | 按规则处理,需要时人工审批命令,不调用审核模型 | 日常使用,安全性优先 |
| 自动审批 | 保留默认权限边界,由审核模型自动批准普通命令,高风险操作转人工确认 | 可信任务的半自动流程 |
| 完全权限 | 确认风险后开启,跳过命令审核和授权等待,但硬性限制仍然生效 | 已评估过的高权限开发场景 |
2. 删除操作的授权边界
文件删除进入审批时只提供 “允许本次” 和 “拒绝”,不保存会话或工作空间级别的删除授权;已有规则可在工作空间权限面板检查。
七、命令安全审核:让模型读脚本,但不让它跑脚本
1. 审核输入
自动审批模式下,硬性权限检查之后,Tokeny 把原始命令、实际外层 Shell、工作目录、工作空间根目录和风险提示交给审核模型。审核模型只有三种合法回应:
{
"action": "read_files",
"paths": ["package.json"],
"reason": "检查构建入口和前后钩子"
}
{
"verdict": "safe",
"risk": "medium",
"reason": "仅构建工作空间内可重建产物"
}
{
"action": "unavailable",
"reason": "必要执行内容依赖未知的运行时输入"
}
以npm run build为例:模型先请求读取package.json,再请求其中引用的构建脚本,最后给出结论。应用本身不解析命令、不推导变量、不展开通配符、不运行脚本、不下载远程代码;发现脚本依赖是审核模型的工作,应用只校验响应结构和读取边界。
2. 预算与边界
| 限制项 | 口径 |
|---|---|
| 取证轮次 | 一次审核最多 4 轮文件取证,格式解析失败可额外重试 3 次,最多 7 次模型调用 |
| 超时 | 所有调用共用一个超时,并受命令工具 30 秒外层截止时间约束 |
| 文件规模 | 最多读取 12 个普通本地文本文件,单个 64KiB,合计 192KiB |
| 路径范围 | 真实路径必须在工作目录或工作空间内,网络路径和设备路径不读取 |
| JSON 解析 | 多个对象、重复字段、截断 JSON 都不采纳,不会从模型续写的多个对象里挑一个 “放行” 结论 |
| 指纹校验 | 已读文件记录真实路径和 SHA-256 指纹,执行前再校验;内容变了、文件被删或链接改指向,都拒绝本次执行,要求重新提交 |
重试用完或审核不可用时,要求用户对这次命令做审批决定,以前保存的授权不能绕过这次审批。
八、目前尚未实现的部分
为避免误读,Tokeny 官方列出当前还没有覆盖的能力和验证项:
- 协议侧:MCP Apps、Sampling、Elicitation、Prompts、Tasks;
- 提案侧:codemode(单独的未来提案);
- 工程侧:真实 OAuth 刷新、并发 401、scope 升级、发行包、更多操作系统验证;
- 测试口径:100/500/1000 个工具规模的目录测试,只记录 Schema 字节数和本地发现耗时,不能作为跨模型成功率或固定 token 节省承诺。
九、结论
Tokeny 这套直连官方 MCP SDK 的方案,核心思路是把 “上下文可见” 和 “执行权限” 拆开处理:可见性负责省上下文、避免工具列表撑爆请求,权限门负责守住本地操作边界,命令审核负责在自动流程里判断脚本风险。工具目录在 run 准入时冻结、每一轮可见子集落盘、恢复时不重新搜索;工具失败交回 Agent 决策,参数不被 “好心” 修改;审核模型可以读文件取证、必须说明理由,执行前还要复核文件指纹。这套设计可以作为桌面 Agent 接入 MCP 时的参考,但 roots 不等于沙箱、可见不等于授权、审核不等于绝对安全,第三方服务来源审查和用户本人的审批确认仍然不能省略。
【相关 FAQ】
问题 1:Tokeny 接入 MCP 为什么说不经过 LangChain,直连官方 MCP SDK 是什么架构?
回答 1:Tokeny 生产路径直接使用官方@modelcontextprotocol/sdk,工具经过 Native binding 和 Permission Gate 权限门后进入自研 Agent Kernel 执行,没有把 LangChain 作为中间框架。这样做是为了在桌面 Agent 里直接控制工具可见性、目录冻结、权限复核和命令审核,减少中间框架对工具身份、Schema 和执行边界的封装干扰。
问题 2:Tokeny 的工具可见性有哪几种方式,为什么说可见性不能替代权限设置?
回答 2:可见性分四种:direct直接可用、gateway按需网关查询调用、deferred搜索后加载、hidden隐藏,还能用toolExposure按精确工具名单独覆盖。可见性只决定模型在本轮能不能看到、检索到某个工具;真正执行时仍要经过工作空间权限、guardrail 规则、安全审核和人工审批等复核,隐藏或搜索加载都不能把不安全的工具变成获准调用。
问题 3:运行中 MCP 服务新增了工具,Tokeny 怎么复核授权边界?
回答 3:Tokeny 把工具分成服务当前目录、本次 run 已授权集合、本轮可见子集三个集合。已授权集合在 run 准入时冻结工具身份、Schema 和绑定,运行期间新出现的工具不会被加进权限范围;搜索只能从已授权集合里选,每轮可见子集和 hash 写入 journal,恢复 run 时沿用冻结视图,只有新用户回合才重新搜索。目录刷新若任一页失败或超限,整次刷新失败,不发布部分结果。
问题 4:Tokeny 的命令安全审核是怎么工作的,审核模型能不能直接运行脚本?
回答 4:不能运行。自动审批模式下,硬性权限检查之后,原始命令、外层 Shell、工作目录、空间根目录和风险提示交给审核模型;模型只能发起读文件取证、给出 safe / 风险结论或返回 unavailable,应用不解析命令、不跑脚本、不下载远程代码。一次审核最多 4 轮取证、重试 3 次,读取文件限 12 个、单个 64KiB,已读文件记录 SHA-256 指纹,执行前再次校验,文件变动就拒绝执行并要求重新提交。
【参考资料】
- [2026-11-15](不经过 LangChain,直接接官方 MCP SDK:Tokeny 的工具可见性、权限复核和命令安全审核)阿里云开发者社区
- [2026-11-15](使用文档 — Tokeny:MCP 工具扩展、安全审批与权限管控)Tokeny 官网
【免责声明】
本文基于 Tokeny 官方文档及公开技术文章整理,仅作技术资讯参考,不构成架构选型建议、安全承诺或代码实现指导。文中涉及的 SDK 版本、配置项、权限模式、审核预算和尚未实现的能力,均以 Tokeny 官方当前版本文档为准;不同 MCP 服务、操作系统和模型表现可能存在差异。命令执行、文件读写和第三方服务接入存在本地风险,落地前应自行完成安全评审、来源审查和权限边界测试,据此操作风险自担。
本文来自作者[相涡路由]投稿,不代表江南网立场,如若转载,请注明出处:https://news.jnwb.net/rgzn/202611/2848.html
评论列表(4条)
我是江南网的签约作者“相涡路由”!
希望本篇文章《不经过 LangChain,直接接官方 MCP SDKTokeny 的工具可见性、权限复核和命令安全审核》能对你有所帮助!
本站[江南网]内容主要涵盖:互联网行业的追踪与探索
本文概览:Tokeny 直连官方 MCP SDK:绕开 LangChain 框架,用工具可见性、权限门复核与命令安全审核管住能操控电脑的 Agent核心结论:桌面 A