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 也能被找到。令牌按以下顺序取第一个:

  1. --token-file <path>;
  2. 环境变量 CHUTE_MCP_TOKEN;
  3. 仅限本机上的服务:端点文件,然后是共享目录里的 control-token。

--url http://<host>:<port>/mcp 让它指向别的设备。CHUTE_MCP_ENDPOINT 指定改读哪个端点文件。--token 和 --token-stdin 会被拒绝:标准输入本身就是 MCP 通道,而写在命令行上的令牌会出现在客户端的配置和进程列表里。连不上服务时,智能体会收到一条说明原因的错误——端口没开会提示检查 external-mcp-server,401 会提示检查令牌。

从电脑连接 iPhone 或 Apple TV

  1. 在设备上监听网络并设置密钥:

    [General]
    external-mcp-server = 0.0.0.0:6180
    external-http-secret = a-long-random-secret
    

    在 iOS 上就是允许通过 Wi-Fi 访问和密钥一行;在 tvOS 上是在同一页把监听地址设为 0.0.0.0 并设置密钥。

  2. 连接 VPN,然后在其他设备(iOS)或局域网地址(tvOS)处读出地址——例如 http://192.168.1.20:6180/mcp。
  3. 在同一网络里的电脑上:

    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 拒绝,也不发送任何跨域头,所以你访问的网站没法借你的浏览器连到这个服务。
S. Smart Rabbit LLC © All Rights Reserved            updated 2026-11-21 15:39:20

本页为英文版的翻译。如内容有出入,以英文版为准。

results matching ""

    No results matching ""