AI Integration (MCP)

Check your Mac / Linux security status directly from AI such as Claude

RoamSwitch includes an MCP (Model Context Protocol) server. Connect it to Claude Desktop / Claude Code and ask “Is my Mac / Linux safe right now?” or “Which ports are exposed externally?”, and it answers based on the diagnosis results RoamSwitch computed.

🔒 Why it's safe

  • Does not change settings: No tool changes settings, defenses or ports. It only writes updates to its own records, such as diagnosis history, log baselines and the npm cache.
  • Fully local: Communicates only over standard input/output and sends no telemetry. External communication is limited to run_npm_audit_signatures (disabled by default) and, on the Linux Server Edition, DNS, RDAP and MTA-STS queries for the domains you list in domain_check_domains. Everything else is 127.0.0.1 and ICMP ping to the gateway (up to 3 packets).
  • Prevents mistaken operations: There are no action tools, so even prompt injection cannot change settings.

Mac and Linux tools also carry MCP annotations (such as readOnlyHint). Only the three above have readOnlyHint set to false, and only run_npm_audit_signatures has openWorldHint set to true. Each row of get_vulnerability_scan_history includes what the probe leaves on the target (sideEffects). Each finding of run_active_vuln_scan includes whether the problem was confirmed or the version merely falls within the CVE's range (evidenceKind).

Setup

Set up in two steps

1Binary location

Bundled with RoamSwitch.app — no separate download or installation needed.

/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer

2aFor Claude Desktop

Add the following to "mcpServers" in ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop.

{
  "mcpServers": {
    "roamswitch": {
      "command": "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
    }
  }
}

2bFor Claude Code

Run the following command once in a terminal.

claude mcp add roamswitch /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer

2cFor OpenAI Codex CLI

Add the following to ~/.codex/config.toml, or run the following command in a terminal.

[mcp_servers.roamswitch]
command = "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
codex mcp add roamswitch -- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer

2dFor OpenCode

Add the following to opencode.json in your project root (or global config ~/.config/opencode/opencode.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "roamswitch": {
        "type": "local",
        "command": ["/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"]
      }
    }
  }
}

💡 Local LLM support: If you work with a local model such as Ollama or LM Studio, you can check safety and ask questions fully offline, even while RoamSwitch has detected a threat and cut the network off in an emergency.

2eFor Antigravity

Add the following to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json at your workspace root).

{
  "mcpServers": {
    "roamswitch": {
      "command": "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
    }
  }
}

* If Antigravity CLI (agy) or similar shows a Hook Failure or a telemetry error when running a tool, set "enabled": false in ~/.gemini/config/plugins/.../hooks.json to disable the hook.

1Binary location

It is bundled with the apt / rpm / Arch packages and placed at /usr/bin/roamswitch-mcp on installation. No separate download or build is needed (same for the client edition and the Server Edition).

/usr/bin/roamswitch-mcp

On the Server Edition (headless operation) too, you can configure the same binary in the same way. For details, see the "AI Agent / MCP Integration" chapter of the "Operations Manual (Linux Server)".

2aFor Claude Desktop

Claude Desktop is not officially available for Linux. If you use an unofficial build (e.g. claude-desktop-debian), add the following to "mcpServers" in ~/.config/Claude/claude_desktop_config.json and restart.

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp"
    }
  }
}

2bFor Claude Code

Run the following command once in a terminal.

claude mcp add roamswitch /usr/bin/roamswitch-mcp

2cFor OpenAI Codex CLI

Add the following to ~/.codex/config.toml, or run the following command in a terminal.

[mcp_servers.roamswitch]
command = "/usr/bin/roamswitch-mcp"
codex mcp add roamswitch -- /usr/bin/roamswitch-mcp

2dFor OpenCode

Add the following to opencode.json in your project root (or global config ~/.config/opencode/opencode.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "roamswitch": {
        "type": "local",
        "command": ["/usr/bin/roamswitch-mcp"]
      }
    }
  }
}

💡 Local LLM support: If you work with a local model such as Ollama or LM Studio, you can check safety and ask questions fully offline, even while RoamSwitch has detected a threat and cut the network off in an emergency.

2eFor Antigravity

Add the following to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json at your workspace root).

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp"
    }
  }
}

* If Antigravity CLI (agy) or similar shows a Hook Failure or a telemetry error when running a tool, set "enabled": false in ~/.gemini/config/plugins/.../hooks.json to disable the hook.

Available tools

Tools (currently 35 on Mac / 45 on Linux — growing)

get_security_report

Diagnoses 23 items on Mac (FileVault, firewall, externally exposed ports, etc.) and 31 client / 42 server items on Linux (kernel hardening, protection of the Docker socket and privileged containers, container runtime isolation, known vulnerabilities, etc.), and returns a score and improvement advice. The Linux numbers are the fixed items; more are added depending on the host.

get_exposed_ports

Lists all listening ports and attaches a verdict on whether each externally exposed one is a known dangerous service (Redis, MongoDB, etc.). Local AI runtimes (Ollama, vLLM, ComfyUI, etc.) are listed in aiRuntimes with a confidence of confirmed or likely (likely goes up to a warning only). On Mac, it sends one HTTP GET to 127.0.0.1 for each exposed port and also uses the response headers in the verdict. On Linux, it decides by port and process name.

get_guard_status

Returns whether each guard is enabled, such as automatic unknown-port blocking, automatic ARP spoofing response, and the USB storage guard, along with the current protection level. For guards that read logs or files, it also returns whether the input is actually being read, and never shows a guard that cannot read as “running”. No detection means “nothing detected in the range checked”.

audit_url_safety

Given an email body or URL, diagnoses phishing, Unicode homograph spoofing, subdomains impersonating well-known brands, and high-risk TLDs, entirely on the device (Zero Telemetry).

get_app_help

Searches, on the device, the official knowledge base covering the specifications, internal behavior, all notification messages, and troubleshooting of every RoamSwitch feature, and returns explanations and advice.

audit_security_logs

Aggregates recent security logs (Sudo authentication failures, SSH brute force, firewall blocks, and so on; on Mac also Gatekeeper and XProtect, on Linux also AppArmor and ClamAV) and returns them with secrets such as API keys and tokens masked. It also includes detection results for new patterns and frequency anomalies (statistical spikes). On Linux, when the journal could not be read, it does not treat 0 items as “nothing happened”; it sets journalReadComplete to false and puts the reason in journalError.

get_notification_history

Returns the history of notifications RoamSwitch has sent (security log-audit anomalies, ClickFix detections, and the like) from the past 7 days, most recent first.

roamswitch://docs/* (MCP Resources)

Official documentation that an AI can read directly as context (feature specifications, explanations of every alert, setup guides, troubleshooting).

Other tools

Tool Platform Summary
audit_secrets Mac / Linux Detects leaked API keys and private keys in text, files, and directories (detected values are output masked). For directories, setting the optional argument include_build_output (boolean) to true also reads folders of publicly served front-end output such as dist and build, which the recursive scan skips (buildOutput is added to the result).
run_active_vuln_scan Mac / Linux A non-destructive, proof-based vulnerability check that targets only 127.0.0.1. It does not connect to external hosts, but because it is a tool that sends network requests, it is disabled by default and requires an opt-in in settings.
get_vulnerability_scan_history Mac / Linux Returns the last recorded result and days elapsed (pass_age) for each probe that run_active_vuln_scan has recorded.
verify_security_findings Mac / Linux Re-evaluates the items of get_security_report against the current state and returns one of stillPresent, resolved or inconclusive, with a reason. Use it to confirm that a fix took effect. Items that cannot be measured are never treated as safe and become inconclusive. Omitting checkIds covers all items (up to 50 on Mac and 64 on Linux). Some Mac items depend on in-app setting values. It is read-only and performs no repairs or setting changes. The result includes verificationStatus and rationale, plus counterEvidence and severityChangesIf if the item still applies.
audit_mcp_configs Mac / Linux Reads the MCP configuration files of AI clients (Claude Desktop, Cursor and others, plus .mcp.json in registered folders) and flags auto-approval without confirmation, plain-text http://, unpinned npx versions and similar. It is read-only and sends nothing. It returns no values or secrets, only items such as server names. Files that cannot be parsed are listed in unreadableFiles.
audit_agent_setup Mac / Linux Reads the instruction files, skills and settings of AI agents (Claude Code, Codex and others), plus VS Code tasks and GitHub Actions in registered folders, and flags text hidden with invisible characters, instructions that fetch and run content as is, overly broad permissions and similar. A match is a place to check, not a verdict of malice. It is read-only, sends nothing and returns no body text or secrets. With format=sarif it returns SARIF 2.1.0.
get_detection_coverage Mac / Linux For each MITRE ATT&CK technique used to weaken defenses, erase traces or persist, it returns whether detection is possible (detects / partial / none), what is not visible (blindSpot) and the guard state (liveState). It runs nothing and sends nothing. none does not mean there was no attack, and liveState is not proof that a guard is working. With format=navigator it returns an ATT&CK Navigator layer (4.5).
run_package_cve_scan Mac / Linux Checks installed packages (Homebrew / dpkg, dnf, and so on) against the local CVE map. It makes no network connections. If the list cannot be obtained, it sets complete to false. For Ubuntu (20.04 to 26.04), it checks only CVSS 7.0 and above that have a fixed version, so “no match” does not mean there are no CVEs. On Mac, results are ordered by severity and then EPSS (epss). For findings a person has accepted, it returns the count (acceptance); acceptance cannot be done through MCP.
run_package_cve_scan_languages Mac / Linux Checks dependency lockfiles for npm, PyPI, crates.io, and others against the same local CVE map. It makes no network connections at all.
run_package_lifecycle_script_scan Mac / Linux Lists the lifecycle scripts (preinstall / install / postinstall / prepare) in the package.json files under a project's node_modules. It only reads files, runs nothing, and makes no network connections. Patterns that look dangerous (such as curl|sh) get a marker for reference, but this is an inventory, not a threat verdict. After a person marks the current state as confirmed, it returns added or changed scripts and the like as drift (only a person can mark a state as confirmed).
run_dependency_source_scan Mac Checks registered project folders for settings that could allow dependency confusion (a public package fetched in place of an internal package with the same name). It covers pip's extra-index-url and npm @scopes whose source is not pinned. In projects with a lockfile, it also reports, at severity “low”, that no setting keeps very recently published versions out (this is not a claim that a bad package exists). It only reads files and makes no network connections. Mac only, Pro.
run_typosquat_scan Mac / Linux Checks whether any dependency name in a project's package.json is only one or two characters away from a well-known npm package (a possible typosquatting attempt). It reads local files only and never contacts a registry. This is a reference-only heuristic, so false positives are possible.
run_npm_audit_signatures Mac / Linux A tool that queries the npm registry (registry.npmjs.org). It runs npm audit signatures to verify the signatures and provenance of installed packages. Disabled by default, and refuses to run until enabled in settings (the Mac version is Pro only).
get_quarantine_status Mac / Linux Returns the malware quarantine vault's contents: original path, detected threat name, quarantine time and size.
get_canary_status Mac / Linux Returns the ransomware canary's decoy-file state plus up to the 50 most recent detected incidents.
get_ransomware_entropy_guard_status Mac / Linux Returns whether generic entropy-based ransomware detection is enabled, and the most recent burst-detection incidents (on Linux, the latest 50: time, pid, process name, affected files, average entropy, and whether the writer was frozen). If the stored file cannot be read, incidentsReadable is false, and an empty list does not mean “nothing detected”. Other users' home paths are shown only to root and administrators. It does not communicate.
get_honeytoken_status Mac / Linux Returns whether the credential honeytokens are enabled, and the most recent access-detection events. On Linux it also returns where the decoys are placed, the state of the monitoring process, and the latest 50 accesses to the decoys (time, kind, path, suspicious process). If the records cannot be read, eventsReadable is false, and an empty list does not mean “no access”. Other users' home paths are shown only to root and administrators. It does not communicate.
get_browser_credential_watch_status Mac Returns whether the browser credential-access watch is enabled and its recent access-detection events.
get_forensic_evidence_bundles Mac Returns the list of forensic evidence bundles (process list, network connections, modified files, and the like) saved when an emergency Air-Gap fired. It also returns, for each bundle, integrity (verified, manifest_altered, artifact_altered:name, artifact_missing:name or not_anchored), and overall chainOk and chainBrokenAt, and missingBundles for bundles that are in the chain but gone. This detects tampering; it does not prevent it.
get_ransomware_recovery_snapshots Mac Returns the APFS recovery snapshots (pre-damage, detection, manual), the recommended one to recover from, the retention-mode state and the snapshot interval. A detection snapshot may already contain encrypted files. Pro only.
search_exec_events Mac / Linux Searches the process execution records. On Mac it uses eslogger records; on Linux it uses the exec recorder (with a hash chain that can detect tampering). You can filter by path, arguments and so on. It also returns the state of the records and whether they can be read. The Mac version is Pro only. Linux records are readable by root only, so it is launched with root privileges.
get_process_tree Mac / Linux Rebuilds the ancestors and descendants of a given process from the execution record. Only processes that the recorder actually saw are known. Pro only on Mac.
get_port_anomaly_incidents Mac / Linux Returns the baseline status of the port anomaly guard, the ports currently auto-blocked, and up to the latest 50 incidents. Auto-blocked ports are a current state with no timestamp, and are distinct from the timestamped incident history. This distinction is written in the annotation field of the response.
get_ssh_guard_incidents Mac / Linux Returns the state and records of the SSH brute-force guard. It includes whether it goes as far as banning or only detects, the sources currently banned and the time remaining, and the latest records (up to 200). Attempted usernames are not stored on Linux and only counted; on Mac they are sanitized and returned, up to 5. It is read-only, and there is no MCP tool to lift a ban. Available on Linux with the Server Edition and with the Client Edition when sshd is running, and on Mac with the Pro version.
get_port_scan_incidents Linux Returns the detection log of port scans (reconnaissance) against this device. It includes source IPs that reached many ports in a short time, the number of ports reached and some of those ports, and whether they were blocked automatically (and for how long).
get_runtime_threat_status Mac Returns whether an Air-Gap isolation triggered by XProtect malware detection has occurred, and the incident that triggered it. When investigating the reason for an Air-Gap, use this tool first.
verify_fim Linux Re-hashes the critical system files and compares them with the baseline to check for tampering. When run as root, the result gains recentIntrusionContext. For each recent change, it contains the process that made the change and the SSH login it belongs to (or the reason it could not be determined).
get_file_scan_guard_status Linux (Server) Returns the settings of the file scan guard (ClamAV) and the state of the quarantine Vault it uses. This tool is for the Server Edition and is not about the client edition's malware guard settings.
get_ebpf_incidents Linux (Server) Returns the current isolation state of the eBPF runtime guard and the incident history of why it was triggered. On the Server Edition, each record gains the time from detection to action (in milliseconds: detect_to_receive_ms, receive_to_action_ms, detect_to_action_ms), and the state of the Falco heartbeat (heartbeat) is also returned.
get_resource_guard_incidents Linux (Server) Returns the history of the resource exhaustion and process anomaly detection guard (memory leaks / crash loops), with confidence tiers. This is a Server Edition guard, so on the client edition the result is always empty.
get_incident_timeline Mac / Linux Combines the detections of each guard into a single timeline (with process lineage and MITRE ATT&CK tags; experimental). Only rows recorded because of another detection carry the ID of the triggering row and the name of the saved evidence bundle (on Linux parent_event_id, root_event_id, evidence_refs; on Mac parentEventID, rootEventID, evidenceRefs).
get_network_history Mac For each Wi-Fi network, records the number of gateways that responded and the time of the last check, and detects other networks with very similar names (Evil Twin candidates). It can also be used to check whether you have connected before.
get_vpn_status Linux (Client) Returns whether VPN on untrusted networks (WireGuard / Tailscale) is enabled, whether the tunnel is actually up, and whether the leak-blocking kill switch is armed.
get_link_guard_status Linux (Client) Returns the settings of Link Guard (which looks at DNS / TLS SNI / HTTP host and blocks phishing and malicious sites), its operating mode (off / warn / block), the allowlist, and the block and warning events from the last 7 days.
get_air_gap_status Linux (Client) Returns whether an emergency Air-Gap isolation (blocking all communication) is active, its reason, the time until automatic release, and all processes currently frozen with SIGSTOP.
get_sharing_services_status Linux (Client) Returns the settings of the feature that automatically stops SSH, Samba, and screen sharing (GNOME Remote Desktop / VNC / xrdp) when you connect to an untrusted network, and the state of the services it stops and restores.
get_bluetooth_guard_status Linux (Client) Returns the Bluetooth Guard setting that force-disables discoverability on untrusted networks, and the controller's live state (powered, discoverable, connected devices).
get_usb_guard_status Linux (Client) Returns the settings of the USB storage guard and the BadUSB keyboard guard, and a list of connected devices and devices awaiting approval. The BadUSB keyboard guard only suppresses input through evdev and does not disable the device on the kernel side.
get_fleet_status Linux Returns the state of Fleet (centralized management for organizations; a feature in preparation for RoamSwitch Business) on this device: whether it is enrolled, the version of the policy in effect, check-in status and so on. It does not return enrollment codes, tokens, keys or license information. Fleet has no remote-command channel, so an administrator cannot isolate or operate this device.
get_sensor_audit_results Mac / Linux Returns the results (pending, completed, failed) of external active audits requested from a paired RoamSwitch Sensor (a separate product running on your own hardware on the same LAN). It covers what cannot be seen from inside the device: whether it is reachable from outside. Requesting audits and pairing cannot be done from this tool.
get_lan_sensor_overview Linux Returns the picture of the LAN seen by a RoamSwitch Sensor running on the same host: devices, VLANs, the state of the capture and what it cannot see, and threat counts. It only reads the Sensor's local socket, and answers available: false with a reason when there is no Sensor. Strings that come from devices are treated as untrusted data.
get_lan_network_threats Linux Returns the LAN threats known to the Sensor on the same host (rogue DHCP server, rogue IPv6 router, ARP and NDP spoofing, DNS tunneling, weak spots of unmanaged devices and more; narrow it with limit and minSeverity). The list is built from the Sensor's notification history (the last 500 events, kept in memory) and its stored light audits, so it is not a complete log. When part of the LAN cannot be seen, zero threats does not mean nothing is wrong.
get_privilege_escalation_paths Linux Runs the bundled PathScope with fixed arguments and returns the paths by which an account reaches root (number and steps, urgent and high fixes with ATT&CK, and the range that could not be collected). It returns no fix commands and runs none. When complete is false (run without root, or part could not be collected), 0 paths is not "safe". Only root and administrators can name another account in start. If PathScope is absent it returns available: false.
get_access_log_report Linux Runs the bundled AccessScope with fixed arguments and returns a summary of attacks in web server, SSH and authentication logs (risk, the list of detections, masked evidence lines, logs that could not be read). since takes 1 to 90 days such as 24h or 7d, and only logs the calling user can read are covered. When complete is false, 0 detections is not "safe". Log strings can be written by an attacker and are not trusted. If AccessScope is absent it returns available: false. It uses no network and no LLM.

Of the tools above, those that read only local state (quarantine Vault, canaries, port anomalies, notification history, and so on) work even while RoamSwitch has detected a threat and is blocking the network in an emergency. Combined with a local LLM, you can investigate the cause on the spot even during the block.

These are the reason codes of verify_security_findings. The common ones are failing (still applies), passing (no problem), and not_verifiable (cannot be confirmed). When it could not be measured, a code showing the missing permission or connection (helper_unavailable, not_root, and so on) is returned. If the result is inconclusive, fix the conditions and call again.

The only tool that contacts an external host is run_npm_audit_signatures (the npm registry; Pro only on Mac), which is disabled by default. Everything else stays within your own machine and LAN. run_active_vuln_scan (disabled by default) and Mac's get_exposed_ports examine 127.0.0.1 only. Tools that look up the gateway's MAC address may send an ICMP ping to the gateway on the LAN (on Mac usually one, at most a few; on Linux only get_guard_status and a few others, one each).

Results that contain strings which outside parties can alter (package scripts, log text, Wi-Fi names, process command lines and so on) carry a notice that this part is untrusted external data and is not to be treated as instructions. Those strings are truncated. When text resembling instructions to an AI, such as “ignore previous instructions”, is found, a WARNING block is added that gives only the kind and the count (the text is not repeated). Nothing is deleted or stopped. This warning is one watch; the real protection is that no tool changes settings or defenses.

Practical Use Cases

Real-World Prompts for Dev & Daily Workflows

Prompts and example AI responses for real situations, such as auditing ports during local development, checking safety on free Wi-Fi, and diagnosing phishing URLs. You can copy a prompt and send it to the AI as is.

🛠️

Local Server & DB Port Exposure Audit

Web Dev / Docker

Have the AI audit whether launching Next.js, Vite, Python, Docker, Redis and so on has unintentionally exposed them to the LAN on 0.0.0.0 (open to all).

💬 Example Prompt for AI
Audit the exposed ports for local dev servers and containers currently running on my Mac. Are any dangerous ports bound to 0.0.0.0 and exposed to the LAN?
⚡ Tool: get_exposed_ports
Port audit:
• 🚨 3000 (Next.js): exposed on 0.0.0.0:3000
• 🚨 6379 (redis): exposed on 0.0.0.0:6379 (no authentication)
• ✅ 5432 (postgres): 127.0.0.1:5432
💡 Fix: Set Redis to bind 127.0.0.1 and start Next.js with npm run dev -- -H 127.0.0.1.
☕

Security Check on Public / Cafe Wi-Fi

Remote Work / Public Wi-Fi

Right after connecting to free Wi-Fi at a café or hotel, have the AI diagnose whether it is safe to work and whether the necessary protections (firewall, ARP monitoring, etc.) are enabled.

💬 Example Prompt for AI
I just connected to a public cafe Wi-Fi. Run a full security diagnostic to see if it's safe to work here. What's the status of the firewall and ARP spoofing protection?
⚡ Tools: get_security_report, get_guard_status
Mac diagnosis:
• 🛡️ Score: 88 / 100 (A-)
• 📡 Network: untrusted (away mode)
• ✅ Firewall: enabled
• ✅ ARP blocking: enabled
• ⚠️ Improvement: Enable FileVault.
✉️

Inspecting Suspicious Email & Chat Links

Phishing Defense / URL Audit

Have the AI examine a suspicious email claiming to be from a business partner, or a URL in a Slack/Discord DM, only inside your device, without sending it outside (Zero Telemetry).

💬 Example Prompt for AI
I received an email with the link 'https://apple.com.login-auth-verify.xyz/account'. Audit this URL for safety before I click it.
⚡ Tool: audit_url_safety
URL diagnosis:
• 🚨 Verdict: Dangerous (8/100)
• ❌ Spoofing: login-auth-verify.xyz made to look like apple.com
• ❌ TLD: .xyz is common in phishing
• 🔒 Zero Telemetry: verified on the device
• 🛑 Recommended: discard and report without opening
🤖

Have an AI agent check port exposure after it finishes work

Agentic AI Workflows

When you leave building and testing services to Claude Code or Antigravity, have it check with MCP tools to prevent unintended port exposure and vulnerabilities.

💬 Example Prompt for AI
Build the project backend API and test suite. Once done, use RoamSwitch MCP to verify that no unintended external ports are listening before completing.
⚡ Tool: get_exposed_ports
AI agent autonomous run summary:
1. Started the Fastify backend server on port 8080.
2. 🔍 RoamSwitch MCP verification: Ran get_exposed_ports and confirmed it is bound to 127.0.0.1:8080 (localhost only), with no exposure outside the LAN.
3. Since there is no exposure, continuing with the integration tests.
📋

Daily Security Check & Markdown Report Export

Compliance & Reporting

Output the Mac's security status as Markdown, for checking company policy, submitting to the IT department, or personal self-checks.

💬 Example Prompt for AI
Generate a clean Markdown summary report of my Mac's current security posture for my daily work log, including any recommended action items.
⚡ Tools: get_security_report, get_guard_status
Report example:
## 🛡️ Mac Security Health Report (2026-08-28)
- Score: 96 / 100 (A+)
- Defenses:
  • FileVault: ✅
  • SIP: ✅
  • Firewall: ✅
  • ARP blocking: ✅
  • DNS threat protection: ✅ (Quad9)
- Recommended: none
🛡️

Verifying USB, Bluetooth & Download Guards

Device & Physical Defense

Check whether each RoamSwitch guard is enabled, such as unknown USB storage protection, Bluetooth monitoring, web/mail download protection and secure DNS switching.

💬 Example Prompt for AI
Are all protection guards (USB storage guard, Bluetooth guard, DNS threat guard, Web download protection) running properly?
⚡ Tool: get_guard_status
Guard status:
• 🛡️ Protection level: Balanced
• ✅ USB: warns about and blocks unregistered USB
• ✅ Bluetooth: monitors unpaired devices
• ✅ Downloads: scanned with ClamAV
• ✅ DNS: blocks C2 and phishing
💡

Asking what a notification means and how to respond, and how to use the app

App Guide / Alert Advice

Get explanations and remedies from the AI, based on the official knowledge base, for notifications and warnings shown on screen and for feature specifications (packet filter, FSEvents, ClamAV, USB protection, etc.).

💬 Pattern A: automatic port blocking during development, and advice on safe settings (web development, Next.js)
RoamSwitch notified: '🚪 Unknown listening port (3000) auto-blocked'. It's my Next.js dev server. How can I safely configure it to run locally?
⚡ Tool: get_app_help / Resource: roamswitch://docs/settings-guide
Answer:
• 🚪 Reason: The development server started on 0.0.0.0 and could be reached from the LAN, so incoming traffic from outside was blocked.
• ⚙️ Action:
  1. Recommended: Start it with npm run dev -- -H 127.0.0.1.
  2. When sharing: Allow 3000 in “Port Diagnosis”.
💬 Pattern B: safety check and cause analysis after an emergency cutoff (after retreating to tethering, etc.)
RoamSwitch triggered an emergency air-gap lockdown on public Wi-Fi due to '🚨 ARP Spoofing Detected'. I switched to mobile tethering. What happened on that Wi-Fi, what defense was active, and what should I do next?
⚡ Tool: get_app_help / Resource: roamswitch://docs/alerts-and-messages
Answer:
• 🔍 Event: It was a man-in-the-middle attack in which a device on the same Wi-Fi impersonated the router.
• 🛡️ Protection: ARP auto-blocking isolated the traffic immediately.
• 🛑 Recommended: Do not go back to that Wi-Fi; keep working over tethering.
💬 Pattern C: automatic USB ejection, and advice on the safe registration procedure
RoamSwitch notified: '🔌 Untrusted USB storage ejected'. It's my own safe USB drive. How can I safely register it as Read-Only?
⚡ Tool: get_app_help / Resource: roamswitch://docs/settings-guide
Answer:
• 🔌 Reason: It was disconnected to prevent data exfiltration and BadUSB attacks through an unregistered USB device.
• ⚙️ Registration: Select it under "Settings" → "USB Storage Protection" → "Add from Connected Devices", and save it as "Read-only (recommended)".
💬 Pattern D: Asking how to recover from "Helper not connected"
The menu bar displays '⚠️ Helper Not Connected'. How can I restore it?
⚡ Tool: get_app_help / Resource: roamswitch://docs/troubleshooting
Answer:
• ⚠️ Cause: The XPC connection to RoamSwitchHelper has been lost.
• 🛠️ Recovery:
  1. Restart the helper:
    sudo killall RoamSwitchHelper
  2. Restart the app.
  3. In "Login Items & Extensions", check that RoamSwitchHelper is allowed.
🧯

After an Air-Gap (emergency cut-off), offline diagnosis with a local LLM and MCP

Incident Response / Local LLM Triage

When Air-Gap (emergency network cut-off) is triggered, for example by ransomware detection, you can no longer communicate with cloud AI such as Claude Desktop. The RoamSwitch MCP server works only over local inter-process communication, so combined with a local LLM such as Ollama, you can keep diagnosing even with no external network at all. Log anomaly detection, tamper detection and matching against known vulnerabilities all complete inside the device.

💬 Example Prompt for AI
RoamSwitch's ransomware protection triggered and the host is now in Air-Gap (emergency network lockdown). There's no network access, but diagnose the current situation: when did it happen, which process and files were affected, is there any tampering in system files, any related suspicious log activity, and any sign a known vulnerability was exploited?
⚡ Tools: get_canary_status, get_port_anomaly_incidents, audit_security_logs, get_quarantine_status (Linux Server: get_ebpf_incidents / Mac: get_runtime_threat_status)
Offline diagnosis result (zero external communication):
• 🐛 Canary triggered: detected encryption of /var/www/decoy_invoice.pdf at 14:32:07, froze and isolated suspicious_enc (PID 8823)
• 🔌 Port monitoring: no new auto-blocks and no additional backdoors
• 📜 Log correlation: authentication failures from sshd surged from 12 minutes before the trigger (Z-score 5.2). A possible entry path
• 🔒 Tamper detection (FIM): no tampering in the critical paths
• 📦 Known vulnerability matching: no critical known vulnerabilities
💡 Recommended action: the compromise is likely limited to under the web root. Before restoring, check the other files in the same directory too.
FAQ

About MCP integration

Q. Does it really never communicate externally?

A. Yes. The MCP server is a local process that runs over standard input/output. It sends no telemetry, and diagnostics are computed on the device. The only external communication is run_npm_audit_signatures (disabled by default) and, in the Linux Server Edition, lookups for the domains listed in domain_check_domains (DNS, RDAP, MTA-STS). Everything else is 127.0.0.1 and pings to the gateway.

Q. Can I use it without the Pro version?

A. The Linux version is free and can use all tools. The Mac version can use most tools even in the free edition, but four (get_ransomware_recovery_snapshots, search_exec_events, get_process_tree, run_npm_audit_signatures) are Pro-only and return an error unless Pro is active. Whether each guard actually takes effect also depends on the Pro license state, so the tools can only confirm the toggle state of the settings.

Q. Which AI clients are supported?

A. Any client that supports the MCP (Model Context Protocol) stdio transport should basically work, beyond those listed above. Operation has been confirmed with Claude Desktop, Claude Code, OpenAI Codex CLI, OpenCode, and Antigravity.

Q. Antigravity shows a "Hook Failure" or telemetry error when calling tools.

A. A PreToolUse hook of an external plugin installed in Antigravity (such as Google Cloud telemetry) may be blocking tool execution. Open ~/.gemini/config/plugins/.../hooks.json and disable it by setting "enabled": false.

Q. Can I still query the MCP server when network access is severed?

A. Yes, with a local LLM (such as Ollama or LM Studio used from OpenCode, etc.). Because everything is processed on the Mac / Linux machine, you can query fully offline even while RoamSwitch has the network under emergency block. If you use a cloud LLM (such as the Claude API), switch to a safe connection such as tethering before querying.