Skip to content

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_routes and 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. Only refresh_dns, which re-resolves the entries already there, is not destructive.
  • custom_add_route and custom_update_route are also open-world: they point the Mac's traffic at a proxy host named in their arguments.
  • set_mode reads status first 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."