Usage¶
VPN Bypass is a macOS menu bar app that decides which traffic uses the VPN and which goes around it. This server gives an agent 23 tools, one per app action, and 3 prompts. Each tool sends one request to the app's control socket and returns the app's answer as JSON, unchanged, both as text and as structuredContent.
Modes¶
| Mode | What goes through the VPN |
|---|---|
bypass |
Everything except the domains on the bypass list and the enabled services, which go around it. |
vpnOnly |
Only the domains and CIDR ranges on the VPN Only list. Everything else goes around it. Services do not apply. |
custom |
Whatever the rules say. Rules match traffic by domain, suffix, IP, CIDR, service or process and send it to a named egress route. Unmatched traffic uses the default route. |
Two kinds of route¶
- A kernel route is an entry VPN Bypass has installed in the macOS routing table right now, one per resolved address or range:
list_active_routes,clear_routes,refresh_routes. - A Custom-mode route is a named egress that rules point at: the VPN (optionally one pinned tunnel), Direct, an HTTP or SOCKS5 proxy, or a Tailscale exit node. The
custom_*tools manage these.
Tools¶
Read tools change nothing and stay registered in read-only mode. The last column is the socket command each tool sends.
| Tool | Read | Needs 4.9.0 | Arguments | Command |
|---|---|---|---|---|
status |
yes | status |
||
get_logs |
yes | yes | limit (1-200, default 50), level |
logs |
set_mode |
mode: bypass, vpnOnly, custom |
status, then mode unless the app is in that mode already |
||
list_domains |
yes | yes | list: bypass or vpnOnly (both when omitted) |
domain.list |
add_domain |
yes | domain (a host name; on bypass also a link, whose host is saved, from VPN Bypass 5.0; on vpnOnly also an IPv4 CIDR), list (default bypass) |
domain.add |
|
remove_domain |
yes | id or domain, list |
domain.rm |
|
set_domain_enabled |
yes | id or domain, enabled, list |
domain.enable, domain.disable |
|
list_services |
yes | yes | service.list |
|
get_service |
yes | yes | id |
service.list |
set_service_enabled |
yes | id, enabled |
service.enable, service.disable |
|
list_active_routes |
yes | yes | source |
routes.active |
clear_routes |
yes | routes.clear |
||
refresh_routes |
yes | refresh |
||
refresh_dns |
yes | dns.refresh |
||
custom_list_routes |
yes | route.list |
||
custom_add_route |
name, type (http, socks5, tailscale, vpn), host, port, user, password, interface, product |
route.add |
||
custom_update_route |
id, then any of name, host, port, user, enabled, password (an empty user or password removes it) |
route.set |
||
custom_set_route_enabled |
id, enabled |
route.enable, route.disable |
||
custom_remove_route |
id |
route.rm |
||
custom_list_rules |
yes | rule.list |
||
custom_add_rule |
match, pattern, route_id |
rule.add |
||
custom_remove_rule |
id |
rule.rm |
||
custom_set_default_route |
route_id |
default |
Every tool has a display title and all four MCP hints: readOnlyHint, destructiveHint, idempotentHint and openWorldHint.
- Every tool that changes where traffic goes is destructive, adds included:
add_domain,remove_domain,set_domain_enabled,set_service_enabled,set_mode,clear_routes,refresh_routesand every Custom-mode write. A client that confirms destructive calls then asks you before an agent, perhaps steered by a web page it read, sends a site around the VPN or through a proxy. Onlyrefresh_dns, which re-resolves the entries already there, is not destructive. custom_add_routeandcustom_update_routeare also open-world: they point the Mac's traffic at a proxy host named in their arguments.set_modereadsstatusfirst and sends nothing when the app is already in the asked-for mode, so it is idempotent. The answer is the same{"mode": ...}the app gives.
Arguments a tool does not declare are refused (the input schemas say additionalProperties: false), and whole numbers such as limit and port are integer. The 8 read tools declare an outputSchema built from the app's result object: it requires no field and allows extra ones, so a field a newer app adds still passes.
Prompts¶
| Prompt | Arguments | What it starts |
|---|---|---|
diagnose_site |
site |
Find out, with read tools only, why a site uses or skips the VPN. Kept in read-only mode. |
bypass_site |
site |
Make a site skip the VPN in the current mode, asking before each change. |
rotate_proxy_port |
route, port |
Point a Custom-mode proxy route at another port, for a new exit IP. |
What happens after a change¶
The domain and service tools call the same code as the app's buttons. The app saves the list before it answers. It adds or removes the kernel routes for that one entry in the background, and only while a VPN is connected. refresh_routes and refresh_dns answer at once and do their work in the background. To see the effect, read list_active_routes or get_logs a few seconds later.
Which tools need VPN Bypass 4.9.0¶
The domain, service, active-route, refresh and log tools use socket commands added in VPN Bypass 4.9.0. An older app answers them with:
this needs VPN Bypass 4.9.0 or newer: the running app is older and does not know the domain.list command. Update VPN Bypass and try again.
Errors¶
A failed call returns an MCP tool error with one line of text:
| Text | Meaning |
|---|---|
VPN Bypass is not running; start the app |
Nothing listens on the socket. The message names the socket as control.sock, never by its full path, which holds your user name. |
this needs VPN Bypass 4.9.0 or newer... |
The app is older than the tool. |
invalid arguments: ... |
The server refused the arguments before sending anything, for example neither id nor domain, a port of 80.5, or an argument the tool does not take (unknown argument enable; custom_update_route takes enabled, host, ...). |
<code>: <message> |
The app's own error, passed through: not_found, invalid_args, already_exists, invalid_port, invalid_type, helper_not_ready, timeout, request_too_large. |
Things to ask¶
- "Is VPN Bypass enforcing right now?"
- "Add example.com to the bypass list, then show me the routes it installed."
- "Which services are enabled?"
- "Show me the last 20 errors in the VPN Bypass log."
- "Switch my residential proxy route to port 24001."