DESKTOP MCP SETUP · ENGLISH

Let your agent handle the VPN step.

Check connection status, list eligible servers, request a connection, and troubleshoot with sanitized diagnostics. You approve connections and server changes inside CryptoMesh VPN.

Requires CryptoMesh VPN 1.2.9 or later on macOS or Windows and an MCP client that supports local stdio servers. Keep the desktop app running.

1. Install the desktop app

Download CryptoMesh VPN, install it, and sign in. Complete any operating-system VPN permissions in the app. Cloud VPN access still requires your usual account entitlement; MCP access does not grant a subscription or bypass device limits.

Quit CryptoMesh VPN before updating. On macOS, install the app in /Applications and open it from there. If prompted, allow its network extension in System Settings → General → Login Items & Extensions → Network Extensions, then request a connection again. Approving the extension does not automatically retry an agent request. On Windows, approve the installer’s administrator prompt. Windows can also request administrator approval when connecting or disconnecting. Disconnect any other WireGuard tunnel before connecting CryptoMesh VPN.

2. Enable agent access

Open Settings → Agent access → Allow local agents. Access is off by default. The screen shows the companion's exact executable path for your installation.

3. Add the companion to your MCP client

Choose a local stdio server and use the executable path shown in the app as its command. No arguments or credentials are needed. If your client uses an mcpServers configuration, merge the matching entry below into your existing configuration.

macOS configuration

{
  "mcpServers": {
    "cryptomesh-vpn": {
      "command": "/Applications/CryptoMesh VPN.app/Contents/MacOS/cryptomesh-mcp"
    }
  }
}

Windows configuration

{
  "mcpServers": {
    "cryptomesh-vpn": {
      "command": "C:\\Program Files\\CryptoMesh VPN\\cryptomesh-mcp.exe"
    }
  }
}

Use the actual path from Settings if you installed elsewhere. Configuration locations and reload steps depend on your MCP client. Restart or reconnect the client after saving. This is a local desktop integration; clients that accept only remote server URLs cannot launch it directly.

4. Try a request

Check my CryptoMesh VPN status and list the available servers. Ask me which one to use, then request a connection and check whether it is verified.

Choose a server from the returned list. When CryptoMesh asks, review and approve the request in the app. A pending request is not a completed connection: wait for the result and check vpn_get_status. Only continue a task that requires VPN protection when the result reports verified: true.

To finish, ask: “Disconnect CryptoMesh VPN.” Disconnect does not require another in-app approval.

The six tools

Tool	What it does	In-app approval
`vpn_get_status`	Read tunnel and verification state.	No
`vpn_list_servers`	List managed servers and paired personal nodes.	No
`vpn_diagnose`	Read sanitized diagnostics.	No
`vpn_select_server`	Change the selected eligible server.	Yes
`vpn_connect`	Request a connection through the normal VPN workflow.	Yes
`vpn_disconnect`	Disconnect and cancel pending agent requests.	No

Connection and selection requests expire after two minutes without approval. Clients can supply an optional request_id of 8–128 letters, digits, underscores, or hyphens to retry the same request without creating another action. Omit it when unused.

Network-device workflows

CryptoMesh supplies the VPN connection step. To administer a router, server, or another network device, use a separate device-specific MCP server, API, or SSH tool with its own permissions. Device reachability depends on your network and personal-node configuration. The VPN companion does not discover or administer devices.

Your controls

The companion communicates with the running app on your computer. It does not expose a remote control endpoint. Its tools exclude VPN private keys, raw profiles, account identifiers, and private LAN addresses. Imported WireGuard profiles, billing, account administration, and personal-node administration are not available through these tools.

Turn off Allow local agents to stop access. Use Rotate local token to replace the local access credential. Do not paste the protected discovery file into your MCP configuration, prompts, or support messages.

Troubleshooting

The companion is missing: Install version 1.2.9 or later. The older public 1.2.8 macOS package does not include the MCP companion.
Agent access is disabled or unavailable: Open the app, enable Allow local agents, and check the executable path in Settings.
The client reports a pending request or times out: Open CryptoMesh and review the approval. Check Recent requests before trying again. When retrying the same action, reuse its request ID if your client supplied one.
The connection is not verified: Ask for vpn_diagnose and inspect the app. Check sign-in, entitlement, device limits, node availability, and operating-system VPN permission. Do not treat an unverified tunnel as protected.

Download the app · Privacy