# 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."
