AI Agent (MCP) PRO PREVIEW
PREVIEW Notice: the MCP server is in internal testing and has not been released. This page describes the build under test: its keys, routes, tool names and app screens may still change before it ships.
[General]
external-mcp-server = 127.0.0.1:6180
The engine of Chute Mac, Chute iOS and Chute tvOS has an MCP (Model Context Protocol) server of its own. An AI agent — Claude Code, Codex or any other client that speaks MCP — connects to it, reads what the engine is doing (status, policies, rules, connections, DNS, the log, the configuration) and changes it: selects a policy, tries a rule, rewrites a section of the configuration, tests the members of a group.
It is built on the routes of the HTTP Control API and signs in with the same secret, but it is a listener of its own, at /mcp on its own port: it needs neither external-http-controller nor the Web Console. It is off by default.
PRO Notice: the MCP server is part of Chute Pro. Without a license the engine does not start it:
external-mcp-serveropens no port, and the configuration can still be edited. Once a license is in force the server starts without restarting Chute, and it stops when the license is gone; the free trial of Chute Mac counts as a license. The HTTP Control API itself is not affected. What the apps show meanwhile is under Without Chute Pro; see also License and Activation.
What it is for
The agent does the reading, so you can ask in your own words. For example:
- "Why does
api.example.comgo out through HK-01?" — the agent asksmatch_rule, which names the rule and the policy, tries a fix withedit_user_rules, and once it works writes it into[Rule]withreplace_profile_section. - "Which nodes in Auto still work?" —
test_policyon the group times every member, one after another, and reports each as it finishes. - "The app can't reach the server since this morning." —
list_connectionswith thefailedfilter,get_logswith a keyword, andrun_diagnosticsfor the network itself. - "Block ads on this site." —
add_rewriteandadd_mitm_hostto try it in the running engine, then the lines to keep in the configuration.
Turning it on
external-mcp-server (Default: disabled)
external-mcp-server = 127.0.0.1:6180
The address and port of the MCP server. This key is Chute's own: Surge and Clash have nothing like it, and importing their configurations does not add it. The address is written as for external-http-controller: 127.0.0.1:6180 for this device only, 0.0.0.0:6180 or *:6180 for every interface, [::]:6180 for IPv6; the whole of 127.0.0.0/8, ::1 and localhost count as loopback. An address that cannot be parsed is a configuration error. The apps use port 6180 when they turn it on.
Signing in. The agent sends Authorization: Bearer <token>, and the token is the HTTP Control API's:
external-http-secret, when the configuration has one;- otherwise the token Chute generates and keeps in the
control-tokenfile of its share folder — generated even whenexternal-http-controlleris off, and shown in the apps; external-http-secret = nonemeans no sign-in at all, and is accepted only on a loopback address.
Off loopback, the MCP server needs an explicit external-http-secret: neither the generated token nor none is enough. Without one it does not start, and the apps show why.
It runs with the engine. It starts when Chute starts and stops when Chute stops, so an agent cannot start Chute, stop it or make the app switch to another configuration. A reload restarts the listener only when its address or the secret changed, and only after the answers already on their way have been written — an agent that changes the MCP server's own address still gets its reply.
external-mcp-mask-secrets (Default: true)
external-mcp-mask-secrets = false
Whether passwords, keys and tokens reach the agent as handles — see Secret masking. Also Chute's own key; it is written into the configuration only when it is false.
In the apps
- Chute iOS: in the configuration editor, External Controller → MCP Server: the switch, Port, Allow Access From Wi-Fi (which listens on
0.0.0.0; the Secret row it then needs is the HTTP Control API's) and Mask Secrets. The Control Panel's AI Agent (MCP) row, under the Web Console, shows Running, Not Listening or Not Configured, and opens a page with the reason the server is not listening, the address for This Device and, off loopback, for Other Devices, the token (hidden until Show Token; tap a row to copy it), CLIENT SETUP with a ready-madeclaude mcp addcommand and JSON, and QUICK ACTIONS. The MCP server runs inside the VPN: with the VPN off, the page says what the current configuration will do. - Chute Mac: the main window's Config tab → General → MCP Server: Enable MCP Server, the address and port, the secret it shares with the HTTP Control API, Mask secrets, and Status & Client Setup…. While Chute runs, AI Agent (MCP)… in the menu bar menu (and in the menu bar panel's … menu) opens a window with the status, the addresses, the token (Show, Copy), whether secrets are masked, and Connect an Agent: the setups for Claude Code over HTTP, for Claude Code through the
chutecommand, and JSON for other clients. - Chute tvOS: Configuration Edit → GENERAL → MCP Server: on or off, Listen Address (
127.0.0.1or0.0.0.0), the port and Mask Secrets. The same page sets the secret, which is the HTTP Control API'sexternal-http-secret: it is shown masked until you ask to see it, left empty it means the token Chute generates, andnoneturns sign-in off, after a warning. It cannot contain spaces or line breaks. Changing it changes how the Web Console and thechutecommand sign in, too. With0.0.0.0and no secret, the page says that the server will not start and lets you set one there. The Control Panel's AI Agent (MCP) row shows the status, the Address, the LAN Address and the Token, hidden until selected; nothing is copied on the TV.
The quick switches — QUICK ACTIONS on iOS, Turn On MCP / Turn Off MCP and Mask secrets in the Mac window, MCP Server and Mask Secrets on the TV's page — change these two keys in the current configuration file and apply it at once; turned on there, the server listens on 127.0.0.1:6180. On iOS they are disabled for a subscription, whose next update would undo them.
Without Chute Pro
Without a license the apps say that the server needs Chute Pro, rather than reporting it as not listening:
- Chute Mac: AI Agent (MCP)… in the menu bar menu and in the menu bar panel's … menu, and Enable MCP Server on the General page, carry the PRO capsule. The AI Agent (MCP) window opens with a Chute Pro note and a Get Chute Pro button, and its status reads Needs Chute Pro, with no address and no token. Turn On MCP opens the Chute Pro window instead of turning the server on; turning it off and Mask secrets work as always. The Chute Pro window lists AI Agent (MCP) among its features.
- Chute iOS and Chute tvOS: the Control Panel's AI Agent (MCP) row and the configuration editor's MCP switch carry the PRO capsule. The status page reads Needs Chute Pro and offers the way to Chute Pro in place of the address and the token; turning the server on with the quick switch there asks for Chute Pro first, as the apps' other Chute Pro switches do.
- On all three, the configuration editor's fields stay editable, and the note that lists the Chute Pro features which did not run this time names the MCP server.
Connecting an agent
Over HTTP
A client that speaks Streamable HTTP connects directly:
- address:
http://<host>:<port>/mcp— for an agent on the same device,http://127.0.0.1:6180/mcp; - header:
Authorization: Bearer <token>, with the token the app shows.
For Claude Code:
claude mcp add --transport http chute http://127.0.0.1:6180/mcp --header "Authorization: Bearer <token>"
For a client configured with JSON:
{"mcpServers": {"chute": {"type": "http", "url": "http://127.0.0.1:6180/mcp", "headers": {"Authorization": "Bearer <token>"}}}}
Chute iOS and Chute Mac copy both with the address and the token filled in. On an iPhone, an agent app on the same iPhone reaches the server at 127.0.0.1 as well.
The server speaks MCP 2026-07-28, and accepts clients of 2025-11-25, 2025-06-18 and 2025-03-26. It keeps no session: every JSON-RPC message is one POST to /mcp, answered with JSON — or, for the long tools, with an event stream — and the connection closes after it. GET, DELETE and OPTIONS are answered with 405, batches (a JSON array) are refused, a request body is limited to 1 MB, and at most 8 connections are served at once.
Through chute mcp
A client that only starts MCP servers as programs it launches — or one whose configuration should not hold the token — uses the chute command-line tool as a relay: chute mcp passes each line it reads to the MCP server and writes each answer back as a line.
claude mcp add chute -- chute mcp
{"mcpServers": {"chute": {"command": "chute", "args": ["mcp"]}}}
On a Mac running Chute that is all it takes: chute mcp reads the address and the token from the endpoint file, at every message, so a Chute started after the client is found too. The token comes from the first of:
--token-file <path>;- the environment variable
CHUTE_MCP_TOKEN; - for a server on this Mac only, the endpoint file, then
control-tokenin the share folder.
--url http://<host>:<port>/mcp points it at another device. CHUTE_MCP_ENDPOINT names an endpoint file to read instead. --token and --token-stdin are refused: standard input is the MCP channel itself, and a token on the command line ends up in the client's configuration and the process list. When the server cannot be reached, the agent receives an error saying why — a closed port points at external-mcp-server, a 401 at the token.
From a computer to an iPhone or Apple TV
On the device, listen on the network and set a secret:
[General] external-mcp-server = 0.0.0.0:6180 external-http-secret = a-long-random-secretOn iOS this is Allow Access From Wi-Fi and the Secret row; on tvOS, Listen Address
0.0.0.0and the secret, on the same page.- Connect the VPN, then read the address under Other Devices (iOS) or LAN Address (tvOS) — for example
http://192.168.1.20:6180/mcp. On the computer, on the same network:
claude mcp add --transport http chute-phone http://192.168.1.20:6180/mcp --header "Authorization: Bearer a-long-random-secret"or, with the secret kept in a file:
chute mcp --url http://192.168.1.20:6180/mcp --token-file ~/.config/chute/phone.token
The address is the device's address on the network, so it changes when the network gives the device another one.
The endpoint file
While the MCP server listens, the engine writes mcp-endpoint into its share folder, readable only by its owner, and deletes it when the server stops. It is a JSON object of strings: running, configured, url, lan_url (off loopback), bind, port, loopback, token, anonymous and mask_secrets — what the apps show. On a Mac it is ~/Library/Application Support/com.R3Studio.Chute-Mac/Share/mcp-endpoint (see File Locations), which is how a local client needs no port and no token. On iPhone and Apple TV it stays inside the app's container: take the address from the app.
Secret masking
What an agent reads goes to the agent's model provider. So, by default, the secrets of the configuration never reach it: each one is replaced by a handle such as <secret:password:3f9c0a1b2e> — its kind and an identifier — wherever it appears, in the configuration and in every other result, the log included. Server addresses stay visible, so the agent can still tell which server a node or a download points at.
[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>
What is masked: proxy passwords, UUIDs, pre-shared keys, private keys, obfs and shadow-tls passwords and tokens such as MASQUE's — those of WireGuard and AmneziaWG sections and of proxy providers' nodes included; the passwords of http-auth, external-http-secret and the password of external-controller-access; ca-p12 and ca-passphrase; the Tailscale auth key; a script's argument=; the path, query and user part of subscription, policy-path, rule set, module and #!MANAGED-CONFIG URLs (the scheme, host and port stay); and the values of [Header Rewrite] headers named Authorization, Proxy-Authorization, or containing token, key, secret, auth, password or cookie. A secret shorter than 8 characters is replaced where it stands as a field's value, but not inside free text such as a log line, where it could not be told from an ordinary word.
Writing back. When the agent writes configuration text back, a handle left as it is turns back into the value it stands for, so the agent can change a node's port, rename it or rearrange a section without knowing its password. A handle may also be moved or copied, with two limits:
- it goes back only into a field of the same kind — a password handle into a password field;
- the line must reach the same server the secret came from: the proxy's server, the URL's host, or the same
[General]key.
A handle elsewhere — on a line for another server, in a rule, made up, or out of date (below) — is refused with the line number and the reason, and nothing is applied: that value is for you to type. A new secret the agent writes out in full is taken as written; it is then, of course, already in the agent's context.
The same value always gets the same handle, so an agent can see that two nodes share a password. A handle lasts as long as the process that issued it — until Chute Mac quits, or until the VPN of Chute iOS or Chute tvOS disconnects; after that it is refused, and the agent reads the configuration again.
Masking covers the configuration's secrets. Credentials in your own traffic — a website's cookies, an Authorization header an app sent — are not configuration secrets and are not masked, which is one more reason they are given only when asked for (below).
Turning it off. external-mcp-mask-secrets = false — or the Mask Secrets switch in the apps — gives the agent every secret as written, and the agent is told so. Do this only when you accept that those credentials enter the context of the agent's model provider.
Third-party content
Request and response headers and bodies, log lines, script output and the text of a module downloaded from a URL are written by others — a website, an app, whoever runs the server. A web page can contain text written to look like instructions to an agent. So:
- by default, tools return metadata only: hosts, URLs, ports, policies, rules, process names, byte counts, times and status;
- the content comes only when the agent asks for it —
get_connectionwithinclude,get_logs,run_script,get_module— and it comes under anuntrustedkey, which the agent is told to read as data, never as instructions.
This keeps the agent's context clean and its token bill small; it is not access control. An agent holding the token can call the HTTP Control API directly and read everything.
Tools
Each tool is marked as one of four kinds, which clients use to decide what to ask you before calling it.
Read-only
| Tool | What it does |
|---|---|
get_status |
Whether the engine runs and how: outbound mode, switches, TUN, listeners, memory, connections, how the previous run ended |
get_network_summary |
The network the device is on — type, Wi-Fi name, router — whether an SSID setting suspends Chute there, and the device's addresses |
get_traffic |
Bytes up and down and the current speeds |
list_policies |
Groups with their current choice, the node they end at and its latency; group for one group in full, detail for every member |
get_policy |
One policy's configuration line and what the engine knows of it now: server, port, UDP, latency, where it leads |
list_rules |
The rules in match order and where each came from; filter narrows them |
match_rule |
Which rule and policy a request would take, before and after its name resolves, without making it |
list_user_rules |
The rules added while the engine runs |
list_connections |
Open or recorded connections, metadata only; filter by host, process, policy, or failed |
get_connection |
One connection; its headers and bodies only when named in include |
get_logs |
Lines of the engine's log, by minimum level and keyword |
get_events |
Notable moments of this run; after for only the new ones |
list_dns_cache |
The DNS records and which server answered each |
query_dns |
Resolves a name through the engine's own resolvers and says which one answered |
geoip_lookup |
Country and ASN of an address or a name |
get_profile |
The running configuration, a page of lines at a time, with its revision |
list_profile_sections |
The configuration's sections, each with its revision and whether it can be written |
get_profile_section |
One section's text and revision |
validate_profile |
Parses a configuration the way a reload would, without applying it |
get_log_level |
The log level and the sections being logged |
list_scripts |
The generic scripts run_script can run |
list_rewrites |
The rewrite and Mock Response rules in force, and the MitM host list |
list_mitm_hosts |
The hosts being decrypted |
list_modules |
The loaded modules, their ids and whether each is on |
get_module |
One module's text |
list_external_resources |
Rule sets, rule providers, proxy providers and modules fetched from elsewhere: when each was updated, how many entries it gave, its last error |
get_tailscale |
The Tailscale node: identity, exit node, DERP, peers with detail |
watch_events |
Watches the engine's events for 1 to 60 seconds and returns all of them |
Tests
These send traffic of their own.
| Tool | What it does |
|---|---|
test_policy |
One HTTPS request through a policy, with status code and time; for a group, every member, reported one by one |
test_policies |
Several policies, or all of them, reported one by one |
ping |
ICMP, or the time to open a TCP connection, from the device directly |
egress_probe |
This device's own address on its physical network |
internet_test |
One request to internet-test-url without any proxy: is there Internet at all |
run_diagnostics |
Engine health, the Internet test, the egress address and a DNS lookup, one step at a time, then a report |
The times test_policy reports for a group's members are HTTPS round trips; a group's own test usually fetches a plain-HTTP URL, so the figures differ from the ones the group chooses by. The group's own test runs afterwards and chooses as it always does.
Settings
| Tool | What it does |
|---|---|
set_outbound_mode |
Rule, global or direct |
select_policy |
A member of a select group, or the global selection (GLOBAL); automatic groups choose for themselves and refuse |
set_feature |
MitM or traffic recording, on or off |
set_log_level |
The log level and the sections logged, without a reload |
edit_user_rules |
Replaces, extends or clears the run-time rules; a line that is not a rule refuses the whole change |
add_mitm_host, remove_mitm_host |
The MitM host list |
add_rewrite, remove_rewrite |
A URL, header or body rewrite or a Mock Response rule, written as its configuration line |
set_modules_enabled |
Turns modules on or off |
update_external_resource |
Fetches a rule set, a rule provider or a proxy provider now |
replace_profile_section |
Replaces one section of the configuration, or adds it, and reloads |
replace_profile |
Replaces the whole configuration and reloads |
Destructive
| Tool | What it does |
|---|---|
reload_profile |
Undoes the run-time changes: rewrites, MitM hosts and module switches go back to what the configuration says |
kill_connection |
Closes one open connection; the app on the other end sees it drop |
flush_dns |
Drops the DNS cache, or one name's record |
run_script |
Runs one of the configuration's generic scripts and returns its output |
How tools answer
- A summary by default. List tools give each entry's key fields;
detail: truegives every field, at more tokens. - Pages. Long lists and texts take
offsetandlimitand returnnext_offsetwhile there is more. - 256 KB at most. A larger result is cut by entries or by lines, never in the middle of one, and says
truncated: truewith thenext_offsetto go on from — what arrives is always valid JSON. - Errors in words. A tool that fails says why in a sentence the agent can act on, rather than a bare status code.
How long a change lasts
On Chute iOS and Chute tvOS, every change is made in the running engine only. Nothing is written to the configuration file or to the app's own settings, so a restart brings back what they say, as with the Web Console.
On Chute Mac, the app keeps these changes, as it keeps the same changes made from its own menus, so they survive a restart — whether an agent makes them or the Web Console, the chute command or the HTTP Control API:
- the outbound mode and the policy selections, the global one included (
set_outbound_mode,select_policy): the app remembers them; - MitM and traffic recording (
set_feature): written into the current configuration file; - the configuration itself (
replace_profile,replace_profile_section): written into the current configuration file, then applied the way the app's Save & Apply applies it.
Their results say persisted: true, and the descriptions the agent reads tell it so in advance. A configuration write is refused, and nothing is written, in these cases:
| Situation | Code | What to do |
|---|---|---|
| The main window has unsaved changes | user_editing |
Save or discard them in the app first |
| The configuration file was changed outside Chute | file_changed |
Reload it in Chute first |
| The current configuration is not a local file | profile_missing |
— |
| The app is showing a dialog | needs_user_action |
Answer it, then try again |
A configuration the engine refuses is not written to the file either. When the app has not finished within 10 seconds the agent receives host_busy: the change may still take effect, so the agent reads the state again before trying again. One thing to know: set_feature switches MitM or traffic recording at once and writes the switch into the file, but does not reload the configuration, so the text and the revision get_profile returns right afterwards are still the old ones until the next reload.
On every platform, the log level, rewrites, MitM hosts, module switches and the run-time rules last for this run only, and a reload of the configuration from the app also undoes the rewrites, MitM hosts and module switches. reload_profile undoes the rewrites, MitM hosts and module switches without a reload; the log level, the app's LAN connections switch, the outbound mode and the policy selections stay as they are. The run-time rules of edit_user_rules survive a reload and are gone when the engine stops.
Editing the configuration
Ask the agent to change the configuration a section at a time: get_profile_section reads one section and its revision, and replace_profile_section writes it back with that revision. If the section changed in between, the write is refused and the agent is told to read it again; a change to another section does not get in the way, so two agents can edit different sections. The whole-file pair, get_profile and replace_profile, works the same with the configuration's revision, but a large configuration does not fit in one answer, and replace_profile takes at most 1 MB.
- A section that holds an
#!includeline, every section after it, and the section that holds#!MANAGED-CONFIGcannot be written this way. - A written section is read back from the reloaded configuration:
[General]and[MITM]values are rendered the way Chute writes them and[WireGuard …]keys are reordered, so the text can differ from what was sent. The answer carries the new revision to use next. - A configuration Chute refuses is not applied; the agent gets the reason. For a managed configuration, the next managed update replaces the change.
Progress for long tools
test_policy on a group, test_policies, run_diagnostics and watch_events report as they go. A client that asks for progress (a progressToken) and accepts an event stream receives one notifications/progress per member, policy, step or event, then the result, and the stream closes; other clients receive the result alone when the tool finishes. A long tool runs for at most 60 seconds and then returns what it has, and at most four stream at once. A client that closes the stream cancels the call; probes already sent still finish and still update the group.
Security
- The token is full control. Whoever holds it can read your configuration, your connection history and your log, change your routing, and run your scripts — and it is the HTTP Control API's token too. Keep it out of shared files and screenshots; to change it, give
external-http-secreta new value. - Listening on the network lets every device on that network try. The connection is plain HTTP, so the token crosses the network unencrypted, and failed attempts are not locked out: use a long random
external-http-secret, only on networks you trust, and go back to127.0.0.1when you are done. run_scriptruns code. It runs only the generic scripts the configuration defines, but whatever a script does — requests, stored values, notifications — it does when the agent asks. An agent allowed to write the configuration can also add a script and then run it; read what it changes.- Web pages are kept out. A request that carries the
Originof a web page other than the server itself is refused with403, and no cross-origin headers are sent, so a site you visit cannot reach the server through your browser.