Install the Xray core
The MCP server does not download binaries: a program that fetches executables from the internet is exactly what we do not want to be. On macOS, Homebrew is the easiest route and verifies what it installs.
Mac: no app, but there is a way out
There is no desktop app for macOS and there will not be one soon. But the MCP server is a Node program that needs no signature, and it brings up exactly the same tunnel.
This is not verified on a Mac
Nobody on the project has run these steps on macOS. The route exists, the code allows for it and it is documented, but we cannot say it works until somebody checks. The diagrams below are illustrations of what you should see, not real screenshots: manufacturing a screenshot of something never run would be exactly the kind of decoration this project does not allow itself. If you try it, write to us: it would be the first confirmation.
Why there is no app, and why this does work
Shipping a network application on macOS requires an Apple developer ID — 99 dollars a year — and going through notarisation. The project runs on voluntary donations and has neither. The MCP server, by contrast, is a Node program you install yourself: it is not a signed application, it asks for no system permissions, and it does not change your Mac's network configuration.
The five steps
Install the MCP server and register it
It is a Node program with no runtime dependencies. Because it is not a desktop app, it needs no Apple signature or notarisation — which is why this route exists on macOS and the other one does not. VPNPRO89_XRAY tells it where the core ended up.
Write your authorisation
Without this file nothing connects, and you write it: if an agent could create it, it would not be an authorisation. The expiry date is mandatory, because a permission with no end date stays on forever. The ids come from local_vpn_list_nodes.
Ask your assistant
It will list the nodes you authorised and ask you to confirm. That confirmation happens outside the chat — a system dialog or your terminal — because an “I confirm” typed into the conversation could have been typed by the agent itself.
Check that traffic really goes through
This is what separates “connected” from “protected”. If both IPs match, the tunnel is not doing its job no matter what the app says. local_vpn_run_diagnostics automates this same comparison.
What you get, and what you do not
What you do get
- Your AI assistant goes out through the tunnel.
- So does any application you point at
127.0.0.1:10808. - Nothing on the system changes: undo it by killing a process.
- The catalogue arrives signed and is verified before use.
What you do not
- It is not a system-wide tunnel: only what points at the proxy goes through.
- There is no kill switch on macOS.
- Safari and other apps keep going out directly unless you configure them.
- There is no graphical interface: you drive it from the assistant or the terminal.
If you would rather wait
Android has a full system tunnel and is on Google Play. Linux has a desktop app in beta. If your Mac is your only machine and this route feels like too much, that is a reasonable answer.