Configuration¶
The server reads two environment variables. It has no config file and no command-line options other than --help and --version.
| Variable | Default | What it does |
|---|---|---|
VPNB_SOCKET |
~/Library/Application Support/VPNBypass/control.sock |
Path of the VPN Bypass control socket. The vpnb command-line client that ships with the app reads the same variable. |
VPN_BYPASS_MCP_READ_ONLY |
unset | Set to 1 to register only the 8 tools that change nothing: status, get_logs, list_domains, list_services, get_service, list_active_routes, custom_list_routes, custom_list_rules, and only the diagnose_site prompt. An unset or empty value, 0, false or no (in any case, with spaces trimmed) leaves it off; any other value turns it on, so a typo never exposes the write tools. |
Read-only mode in a client¶
{
"mcpServers": {
"vpn-bypass": {
"command": "npx",
"args": ["-y", "vpn-bypass-mcp"],
"env": { "VPN_BYPASS_MCP_READ_ONLY": "1" }
}
}
}
For Claude Code:
Timeouts¶
A read tool waits up to 35 seconds for the app (the app itself gives up on a read after 30 seconds and answers timeout). A tool that changes something waits up to 120 seconds, because the app answers only after the change is saved. When a change times out, the server says so and tells the agent to read the current state before retrying, since the change may still land.
Security¶
- The control socket is a UNIX socket in your home folder, readable only by your user, and the app refuses any other user. The server opens no network port.
- A proxy password given to
custom_add_routeorcustom_update_routegoes to the app in a separatesecretsfield. The app never sends it back, and the server never logs or echoes it. - The server writes its log to stderr: one start line with the version, the tool count, read-only or not, and the socket path. It logs no tool arguments. Tool results, which go to the model, name the socket as
control.sockonly. - Every tool that changes where traffic goes is marked destructive, so a client that confirms destructive calls asks you first (Usage).
- The npm package checks the downloaded binary against
checksums.txtshipped inside the package by the release workflow, so the hashes are covered by npm's provenance. It downloads only from GitHub over HTTPS, and stops at 64 MiB.