AI 智能体(MCP) PRO PREVIEW
PREVIEW 提示:MCP 服务仍在内部测试,尚未发布。本页描述的是测试中的构建:键名、路由、工具名和各端界面在正式发布前仍可能变化。
[General]
external-mcp-server = 127.0.0.1:6180
Chute Mac、Chute iOS 和 Chute tvOS 的引擎自带一个 MCP(Model Context Protocol)服务。AI 智能体——Claude Code、Codex,或任何支持 MCP 的客户端——连上它,就能读取引擎在做什么(状态、策略、规则、连接、DNS、日志、配置),也能改动它:选择策略、试一条规则、改写配置里的一节、给策略组的成员测速。
它建立在 HTTP 控制 API 的路由之上,鉴权也用同一个密钥,但它有自己的监听器,在自己的端口上的 /mcp:既不需要 external-http-controller,也不需要 Web 控制台。默认关闭。
PRO 提示:MCP 服务属于 Chute Pro。没有许可证时,引擎不会启动它:写了
external-mcp-server也不会打开端口,配置照样可以编辑。许可证生效后,服务无需重启 Chute 就会启动;许可证失效时服务随之停止。Chute Mac 的免费试用期内也算有许可证。HTTP 控制 API 本身不受影响。在此期间各端应用显示什么,见没有 Chute Pro 时;另见许可证与激活。
能用来做什么
阅读的活儿交给智能体,你用自己的话问就行。例如:
- 「为什么
api.example.com走了 HK-01?」——智能体调用match_rule,它会指出命中的规则和策略;再用edit_user_rules试一个改法,确认有效后用replace_profile_section写进[Rule]。 - 「Auto 里哪些节点还能用?」——对策略组调用
test_policy,逐个给每个成员测速,测完一个报一个。 - 「这个 App 从今早起连不上服务器。」——
list_connections加failed过滤,get_logs按关键字查,再用run_diagnostics检查网络本身。 - 「把这个网站的广告去掉。」——先用
add_rewrite和add_mitm_host在运行中的引擎里试,再把要保留的行写进配置。
开启
external-mcp-server(默认:禁用)
external-mcp-server = 127.0.0.1:6180
MCP 服务的地址和端口。这是 Chute 自己的键:Surge 和 Clash 都没有对应的写法,导入它们的配置也不会生成这一行。地址的写法与 external-http-controller 相同:127.0.0.1:6180 只给本机用,0.0.0.0:6180 或 *:6180 监听所有网卡,IPv6 写 [::]:6180;整个 127.0.0.0/8、::1 和 localhost 都算回环。解析不了的地址算作配置错误。各端应用开启它时使用端口 6180。
鉴权。智能体发送 Authorization: Bearer <token>,令牌就是 HTTP 控制 API 的那一个:
- 配置里写了
external-http-secret,就用它; - 没写,就用 Chute 生成、保存在共享目录
control-token文件里的令牌——即使没开external-http-controller也会生成,并在各端应用里显示; external-http-secret = none表示完全不鉴权,只在回环地址上被接受。
绑定到非回环地址时,MCP 服务必须有显式的 external-http-secret:生成的令牌和 none 都不行。没有它就不会启动,各端应用会显示原因。
它随引擎运行。Chute 启动时它启动,Chute 停止时它停止,所以智能体没法启动或停止 Chute,也没法让应用切换到另一份配置。重载时,只有地址或密钥变了才会重启监听器,而且要等已经在路上的应答都写完——即使智能体改的正是 MCP 服务自己的地址,它也能收到这次的回复。
external-mcp-mask-secrets(默认:true)
external-mcp-mask-secrets = false
密码、密钥和令牌是否以句柄的形式交给智能体——见密钥遮蔽。这同样是 Chute 自己的键;只有为 false 时才会写进配置。
在各端应用里
- Chute iOS:配置编辑器 → 外部控制器 → MCP 服务:开关、端口、允许通过 Wi-Fi 访问(即监听
0.0.0.0;这时需要的密钥一行就是 HTTP 控制 API 的密钥)和遮蔽密钥。控制面板里 Web 控制台下方的 AI 智能体(MCP) 一行显示运行中、未监听或未配置,点开后是一页:服务没在监听的原因、本设备的地址以及(非回环时)其他设备的地址、令牌(点显示令牌才显示;点按一行即可复制)、客户端配置(现成的claude mcp add命令和 JSON),以及快捷操作。MCP 服务运行在 VPN 里:VPN 关闭时,这一页会说明当前配置启动后会怎样。 - Chute Mac:主窗口的配置标签页 → 通用 → MCP 服务:启用 MCP 服务、地址和端口、与 HTTP 控制 API 共用的密钥、遮蔽密钥,以及状态与客户端设置…。Chute 运行时,菜单栏菜单(以及菜单栏面板的 … 菜单)里的 AI 智能体(MCP)… 会打开一个窗口:状态、地址、令牌(显示、复制)、密钥是否遮蔽,以及连接智能体:经 HTTP 接入 Claude Code 的设置、经
chute命令接入 Claude Code 的设置,以及给其他客户端的 JSON。 - Chute tvOS:配置编辑 → 通用 → MCP 服务:开或关、监听地址(
127.0.0.1或0.0.0.0)、端口和遮蔽密钥。同一页还可以设置密钥,也就是 HTTP 控制 API 的external-http-secret:默认打码显示,可以选择显示原文;留空表示使用 Chute 生成的令牌;none表示不鉴权,设置前会有危险提示。密钥不能包含空格或换行。改了它,Web 控制台和chute命令的鉴权也会随之改变。监听0.0.0.0却没有密钥时,这一页会说明服务不会启动,并让你直接在这里设置。控制面板里的 AI 智能体(MCP) 一行显示状态、地址、局域网地址和令牌,令牌选中后才显示;电视上不提供复制。
快捷开关——iOS 的快捷操作、Mac 窗口里的开启 MCP / 关闭 MCP 和遮蔽密钥、电视那一页上的 MCP 服务和遮蔽密钥——直接改当前配置文件里的这两个键并立即应用;从这里开启时,服务监听 127.0.0.1:6180。在 iOS 上,当前配置是订阅时这些开关不可用,因为下次更新订阅会把改动冲掉。
没有 Chute Pro 时
没有许可证时,各端应用会说明服务需要 Chute Pro,而不是把它报告为未监听:
- Chute Mac:菜单栏菜单和菜单栏面板 … 菜单里的 AI 智能体(MCP)…,以及通用页的启用 MCP 服务,都带 PRO 胶囊。AI 智能体(MCP)窗口顶部是 Chute Pro 提示和获取 Chute Pro按钮,状态显示需要 Chute Pro,不显示地址和令牌。点开启 MCP会打开 Chute Pro 窗口,而不是开启服务;关闭服务和遮蔽密钥照常可用。Chute Pro 窗口的功能列表里有 AI 智能体(MCP)一行。
- Chute iOS 和 Chute tvOS:控制面板的 AI 智能体(MCP)一行和配置编辑器里的 MCP 开关带 PRO 胶囊。状态页显示需要 Chute Pro,在原本显示地址和令牌的位置给出获取 Chute Pro 的入口;用那一页的快捷开关开启服务时,会先要求 Chute Pro,和应用里其他 Chute Pro 开关一样。
- 三端的配置编辑器里,相关字段都照样可以编辑;列出「这次运行没有生效的 Chute Pro 功能」的说明里会写上 MCP 服务。
连接智能体
经 HTTP
支持 Streamable HTTP 的客户端可以直接连接:
- 地址:
http://<host>:<port>/mcp——同一台设备上的智能体用http://127.0.0.1:6180/mcp; - 请求头:
Authorization: Bearer <token>,令牌就是应用里显示的那一个。
Claude Code:
claude mcp add --transport http chute http://127.0.0.1:6180/mcp --header "Authorization: Bearer <token>"
用 JSON 配置的客户端:
{"mcpServers": {"chute": {"type": "http", "url": "http://127.0.0.1:6180/mcp", "headers": {"Authorization": "Bearer <token>"}}}}
Chute iOS 和 Chute Mac 复制出来的这两样已经填好了地址和令牌。在 iPhone 上,同一台 iPhone 里的智能体 App 也通过 127.0.0.1 连接。
服务端实现的是 MCP 2026-07-28,同时接受 2025-11-25、2025-06-18、2025-03-26 的客户端。它不保留会话:每条 JSON-RPC 消息是一次发往 /mcp 的 POST,应答是 JSON——长时间运行的工具则是事件流——应答之后连接关闭。GET、DELETE 和 OPTIONS 返回 405,批量请求(JSON 数组)会被拒绝,请求体上限 1 MB,同时最多服务 8 个连接。
经 chute mcp
只会以子进程方式启动 MCP 服务的客户端——或者不想在配置里写令牌的客户端——可以把 chute 命令行工具当作中继:chute mcp 把读到的每一行转给 MCP 服务,再把每个应答写回一行。
claude mcp add chute -- chute mcp
{"mcpServers": {"chute": {"command": "chute", "args": ["mcp"]}}}
在运行着 Chute 的 Mac 上,这样就够了:chute mcp 每处理一条消息都会从端点文件读取地址和令牌,所以比客户端晚启动的 Chute 也能被找到。令牌按以下顺序取第一个:
--token-file <path>;- 环境变量
CHUTE_MCP_TOKEN; - 仅限本机上的服务:端点文件,然后是共享目录里的
control-token。
--url http://<host>:<port>/mcp 让它指向别的设备。CHUTE_MCP_ENDPOINT 指定改读哪个端点文件。--token 和 --token-stdin 会被拒绝:标准输入本身就是 MCP 通道,而写在命令行上的令牌会出现在客户端的配置和进程列表里。连不上服务时,智能体会收到一条说明原因的错误——端口没开会提示检查 external-mcp-server,401 会提示检查令牌。
从电脑连接 iPhone 或 Apple TV
在设备上监听网络并设置密钥:
[General] external-mcp-server = 0.0.0.0:6180 external-http-secret = a-long-random-secret在 iOS 上就是允许通过 Wi-Fi 访问和密钥一行;在 tvOS 上是在同一页把监听地址设为
0.0.0.0并设置密钥。- 连接 VPN,然后在其他设备(iOS)或局域网地址(tvOS)处读出地址——例如
http://192.168.1.20:6180/mcp。 在同一网络里的电脑上:
claude mcp add --transport http chute-phone http://192.168.1.20:6180/mcp --header "Authorization: Bearer a-long-random-secret"或者把密钥放在文件里:
chute mcp --url http://192.168.1.20:6180/mcp --token-file ~/.config/chute/phone.token
这个地址是设备在网络上的地址,网络给设备分配了别的地址时它就会变。
端点文件
MCP 服务监听期间,引擎会把 mcp-endpoint 写进共享目录,只有属主可读;服务停止时删除。它是一个值全为字符串的 JSON 对象:running、configured、url、lan_url(非回环时)、bind、port、loopback、token、anonymous 和 mask_secrets——也就是各端应用显示的那些。在 Mac 上它位于 ~/Library/Application Support/com.R3Studio.Chute-Mac/Share/mcp-endpoint(见文件位置),本机的客户端因此不需要知道端口和令牌。在 iPhone 和 Apple TV 上它留在应用的容器里:地址请从应用里取。
密钥遮蔽
智能体读到的内容会发给它的模型提供方。所以默认情况下,配置里的密钥永远不会交给它:每个密钥无论出现在哪里——配置里,还是其他任何结果里,日志也算——都会被换成一个句柄,例如 <secret:password:3f9c0a1b2e>,由密钥的类别和一个标识组成。服务器地址照常可见,所以智能体仍然看得出节点或下载指向的是哪台服务器。
[Proxy]
HK-01 = trojan, hk.example.com, 443, password=<secret:password:3f9c0a1b2e>, sni=hk.example.com
[Proxy Group]
Sub = select, policy-path=https://sub.example.com<secret:url_secret:8d2e4f6a1c>
会被遮蔽的:代理的密码、UUID、预共享密钥、私钥、obfs 和 shadow-tls 的密码,以及 MASQUE 的 token 这类令牌——WireGuard、AmneziaWG 段和代理提供者的节点里的也包括在内;http-auth 的各个密码、external-http-secret、external-controller-access 的密码;ca-p12 和 ca-passphrase;Tailscale 的 auth key;脚本的 argument=;订阅、policy-path、规则集、模块和 #!MANAGED-CONFIG URL 的路径、查询串和用户信息部分(scheme、主机和端口保留);以及 [Header Rewrite] 里名为 Authorization、Proxy-Authorization,或名字里含 token、key、secret、auth、password、cookie 的请求头的值。短于 8 个字符的密钥只在它作为字段值出现的位置被替换,不会在日志行这类自由文本里替换,因为在那里它和普通的词分不开。
写回。智能体写回配置文本时,原样保留的句柄会还原成它代表的值,所以智能体不知道密码也能改节点的端口、改名或调整一节的顺序。句柄也可以移动或复制,但有两个限制:
- 只能回到同类的字段——密码句柄只能用在密码字段;
- 这一行连接的必须是密钥来源的同一台服务器:代理的服务器、URL 的主机,或同一个
[General]键。
用在别处的句柄——指向别的服务器的行、规则里、编造的、已经过期的(见下文)——都会被拒绝,并指出行号和原因,什么都不会生效:那个值需要你自己填写。智能体完整写出的新密钥会照收;当然,它这时已经进入了智能体的上下文。
同一个值总是对应同一个句柄,所以智能体看得出两个节点共用一个密码。句柄只在签发它的进程存续期间有效——到 Chute Mac 退出,或 Chute iOS、Chute tvOS 的 VPN 断开为止;之后它会被拒绝,让智能体重新读取配置。
遮蔽针对的是配置里的密钥。你自己流量里的凭据——网站的 Cookie、某个 App 发出的 Authorization 请求头——不是配置里的密钥,不会被遮蔽,这也是它们只在明确要求时才给出的原因之一(见下文)。
关闭遮蔽。external-mcp-mask-secrets = false——或者应用里的遮蔽密钥开关——会把所有密钥按原文交给智能体,并告诉它这一点。只有在你接受这些凭据进入智能体模型提供方的上下文时才这样做。
第三方内容
请求和响应的头与正文、日志行、脚本输出、从 URL 下载的模块文本,都是别人写的——某个网站、某个 App、服务器的运营方。网页里完全可以藏着伪装成给智能体下指令的文字。所以:
- 默认情况下,工具只返回元数据:主机、URL、端口、策略、规则、进程名、字节数、耗时和状态;
- 内容只在智能体明确要求时才给出——
get_connection带include、get_logs、run_script、get_module——并放在untrusted键下,智能体会被告知这部分是数据,而不是指令。
这样做是为了让智能体的上下文干净、少花 token,并不是访问控制。拿着令牌的智能体可以直接调用 HTTP 控制 API,什么都读得到。
工具
每个工具都标注为四类之一,客户端据此决定调用之前要不要先问你。
只读
| 工具 | 作用 |
|---|---|
get_status |
引擎是否在运行、怎样运行:出站模式、各项开关、TUN、监听器、内存、连接数、上次运行如何结束 |
get_network_summary |
设备所在的网络——类型、Wi-Fi 名称、路由器——SSID 设置是否让 Chute 在这里暂停,以及设备的地址 |
get_traffic |
上下行字节数和当前速度 |
list_policies |
策略组及其当前选择、最终落到的节点及其延迟;group 给出某一组的全部,detail 给出所有成员 |
get_policy |
某个策略的配置行,以及引擎当前掌握的情况:服务器、端口、UDP、延迟、最终去向 |
list_rules |
按匹配顺序列出规则及各自的来源;filter 可缩小范围 |
match_rule |
一个请求会命中哪条规则、走哪个策略,域名解析前后各算一遍,不真的发出请求 |
list_user_rules |
引擎运行期间添加的规则 |
list_connections |
打开着的或已记录的连接,只有元数据;可按主机、进程、策略或是否失败过滤 |
get_connection |
单个连接;请求头和正文只在 include 里点名时才给 |
get_logs |
引擎日志的行,可按最低级别和关键字过滤 |
get_events |
本次运行的关键事件;after 只取新的 |
list_dns_cache |
DNS 记录,以及每条由哪台服务器应答 |
query_dns |
用引擎自己的解析器解析一个域名,并说明是哪台服务器应答的 |
geoip_lookup |
某个地址或域名的国家和 ASN |
get_profile |
运行中的配置,一次一页,附带 revision |
list_profile_sections |
配置的各节,每节附带 revision 以及能否写入 |
get_profile_section |
某一节的文本和 revision |
validate_profile |
像重载那样解析一份配置,但不应用 |
get_log_level |
日志级别和正在记录的分区 |
list_scripts |
run_script 能运行的 generic 脚本 |
list_rewrites |
生效中的改写和模拟响应规则,以及 MitM 主机列表 |
list_mitm_hosts |
正在解密的主机 |
list_modules |
已加载的模块、它们的 id,以及是否启用 |
get_module |
某个模块的文本 |
list_external_resources |
从别处获取的规则集、规则提供者、代理提供者和模块:各自的更新时间、条目数和最近一次错误 |
get_tailscale |
Tailscale 节点:身份、出口节点、DERP,detail 给出各对端 |
watch_events |
观察 1 到 60 秒内引擎的事件,结束时全部返回 |
测试
这些工具会自己发出流量。
| 工具 | 作用 |
|---|---|
test_policy |
经某个策略发一个 HTTPS 请求,给出状态码和耗时;对策略组则测每个成员,逐个报告 |
test_policies |
测多个策略或全部策略,逐个报告 |
ping |
从设备直接发 ICMP,或测量建立 TCP 连接的时间 |
egress_probe |
本设备在物理网络上的地址 |
internet_test |
不经任何代理请求一次 internet-test-url:到底有没有网 |
run_diagnostics |
依次检查引擎健康、联网测试、出口地址和一次 DNS 查询,最后给出一份报告 |
test_policy 对组成员报告的耗时是 HTTPS 往返;策略组自己的测速通常请求的是明文 HTTP 地址,所以两边的数字不同,策略组并不按这里的数字选择。测完之后会照常启动策略组自己的测速,由它照常选择。
改设置
| 工具 | 作用 |
|---|---|
set_outbound_mode |
规则、全局或直连 |
select_policy |
选择 select 组的某个成员,或全局选择(GLOBAL);自动组自己做选择,会拒绝 |
set_feature |
打开或关闭 MitM、流量录制 |
set_log_level |
日志级别和记录的分区,不需要重载 |
edit_user_rules |
替换、追加或清空运行时规则;有一行不是规则,整批改动都会被拒绝 |
add_mitm_host、remove_mitm_host |
MitM 主机列表 |
add_rewrite、remove_rewrite |
URL、Header 或 Body 重写规则,或模拟响应规则,按配置行的写法给出 |
set_modules_enabled |
启用或停用模块 |
update_external_resource |
立即获取某个规则集、规则提供者或代理提供者 |
replace_profile_section |
替换配置里的某一节(或新增一节),然后重载 |
replace_profile |
替换整份配置,然后重载 |
破坏性
| 工具 | 作用 |
|---|---|
reload_profile |
撤销运行时改动:改写、MitM 主机和模块开关恢复成配置里的样子 |
kill_connection |
关闭一个打开着的连接;另一端的 App 会看到连接断开 |
flush_dns |
清空 DNS 缓存,或删除某个域名的记录 |
run_script |
运行配置里的某个 generic 脚本,返回它的输出 |
工具怎样应答
- 默认给摘要。列表类工具只给每项的关键字段;
detail: true给出全部字段,代价是更多 token。 - 分页。长列表和长文本接受
offset和limit,还有下一页时返回next_offset。 - 最多 256 KB。更大的结果按条目或按行截断,绝不从中间截开,并带上
truncated: true和继续用的next_offset——收到的永远是合法的 JSON。 - 用人话报错。工具失败时会用一句智能体能据此行动的话说明原因,而不是只给一个状态码。
改动能保留多久
在 Chute iOS 和 Chute tvOS 上,所有改动都只在运行中的引擎里生效。什么都不会写进配置文件,也不会写进应用自己的设置,所以重启之后会恢复成它们的样子,这和 Web 控制台相同。
在 Chute Mac 上,下面这些改动由应用保留,和在应用自己的菜单里做同样的改动一样,重启之后依然有效——不论是智能体做的,还是经 Web 控制台、chute 命令或 HTTP 控制 API 做的:
- 出站模式和策略选择,包括全局选择(
set_outbound_mode、select_policy):由应用记住; - MitM 和流量记录开关(
set_feature):写进当前配置文件; - 配置本身(
replace_profile、replace_profile_section):写进当前配置文件,再按应用保存并应用的方式生效。
这些工具的结果会带 persisted: true,智能体读到的工具说明也会事先告诉它这一点。下列情况下,写入配置会被拒绝,什么都不会写入:
| 情况 | 错误码 | 你该怎么做 |
|---|---|---|
| 主窗口里有未保存的修改 | user_editing |
先在应用里保存或放弃这些修改 |
| 配置文件在 Chute 之外被改过 | file_changed |
先在 Chute 里重新加载它 |
| 当前配置不是本地文件 | profile_missing |
— |
| 应用正弹着对话框 | needs_user_action |
处理完对话框再试 |
被引擎拒绝的配置也不会写进文件。应用 10 秒内没有完成时,智能体会收到 host_busy:改动仍可能生效,所以智能体会先重新读取状态,再决定是否重试。需要知道的一点:set_feature 会立即切换 MitM 或流量记录,并把开关写进文件,但不会重载配置,所以紧接着 get_profile 读到的配置文本和 revision 仍是旧的,直到下次重载。
在所有平台上,日志级别、改写、MitM 主机、模块开关和运行时规则都只在本次运行中有效;从应用里重载配置,也会撤销改写、MitM 主机和模块开关。reload_profile 不重载就能撤销改写、MitM 主机和模块开关;日志级别、应用的局域网连接开关、出站模式和策略选择保持不变。edit_user_rules 的运行时规则重载之后仍然保留,引擎停止时才消失。
修改配置
让智能体一节一节地改配置:get_profile_section 读取一节及其 revision,replace_profile_section 带着这个 revision 写回。如果这一节在此期间被改过,写入会被拒绝,智能体会被告知重新读取;改别的节不会妨碍它,所以两个智能体可以同时改不同的节。整份读写的 get_profile 和 replace_profile 也是一样,用的是整份配置的 revision,但大配置一次装不下,而且 replace_profile 最多接受 1 MB。
- 含
#!include行的节、它之后的所有节,以及含#!MANAGED-CONFIG的那一节,不能用这种方式写入。 - 写入的节会从重载后的配置里读回:
[General]和[MITM]的值按 Chute 的写法重新生成,[WireGuard …]的键会重新排序,所以文本可能和发送的不一样。应答里带有下次要用的新 revision。 - Chute 拒绝的配置不会被应用,智能体会拿到原因。对于托管配置,下次托管更新会覆盖这次改动。
长时间运行的工具会报告进度
对策略组的 test_policy、test_policies、run_diagnostics 和 watch_events 会边做边报告。请求进度(带 progressToken)并接受事件流的客户端,会按成员、策略、步骤或事件逐条收到 notifications/progress,然后收到结果,流随即关闭;其他客户端则在工具结束时一次性收到结果。长时间运行的工具最多运行 60 秒,到时返回已有的结果;同时最多四条流。客户端关掉流就等于取消这次调用;已经发出的测速照样跑完,照样更新策略组。
安全
- 令牌等于完全控制。拿到它的人能读你的配置、连接历史和日志,能改你的分流,能运行你的脚本——而且它同时也是 HTTP 控制 API 的令牌。别把它放进共享的文件和截图;要更换,就给
external-http-secret设一个新值。 - 监听网络意味着这个网络里的每台设备都可以来试。连接是明文 HTTP,令牌在网络上不加密传输,失败的尝试也不会被封禁:请使用足够长的随机
external-http-secret,只在你信任的网络里这样做,用完改回127.0.0.1。 run_script会执行代码。它只能运行配置里定义的 generic 脚本,但脚本做的一切——发请求、存数据、发通知——都会在智能体要求时发生。被允许写配置的智能体还可以先加一个脚本再运行它;请看清它改了什么。- 网页被挡在外面。带着服务自身以外网页
Origin的请求会以403拒绝,也不发送任何跨域头,所以你访问的网站没法借你的浏览器连到这个服务。
本页为英文版的翻译。如内容有出入,以英文版为准。