AI Integration (MCP)

Ask AI assistants like Claude directly about your Mac / Linux security status

Q: Which AI clients are supported?

Basically any client that supports the MCP (Model Context Protocol) stdio transport. It has been verified with Claude Desktop, Claude Code, OpenAI Codex CLI, OpenCode and Antigravity.

RoamSwitch bundles a read-only MCP (Model Context Protocol) server. Connect it to an MCP client and just ask, in plain language, "is my Mac / Linux machine secure right now?" or "what ports are exposed?" — you'll get answers grounded in RoamSwitch's own accurate diagnostics, not guesswork. It can't switch lockdown levels, isolate ports, or perform any other action; communication with your AI client stays entirely on-device over stdio (an extension of our Zero Telemetry policy).

🔒 Why it's safe

Read-only: Only security diagnostics, port monitoring, and guard-setting checks. No operational tools like switching lockdown, isolating ports, or ejecting devices are implemented.
Fully local: Communication with your AI client is stdio only, and stays between the client (Claude Desktop/Code, etc.) and the RoamSwitch process on your Mac / Linux machine. No telemetry is ever sent. The network is used only by opt-in features that are disabled by default: the vulnerability check that probes only your own machine (127.0.0.1), and the npm signature check that queries the npm registry.
No accidental changes: Since there are no operational tools, there's no risk of a prompt injection or similar accidentally changing your firewall or network settings.

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

Just run the following command once in your 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 command below in your 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).

{
  "mcp": {
    "roamswitch": {
      "type": "local",
      "command": ["/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"]
    }
  }
}

💡 Local LLM Support: When paired with local models via Ollama or LM Studio, you can query RoamSwitch for safety checks and advice completely offline—even while RoamSwitch has severed external network access due to active threat containment.

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"
    }
  }
}

* Note: If you encounter Hook Failure or telemetry errors in Antigravity CLI (agy), disable the hook by setting "enabled": false in ~/.gemini/config/plugins/.../hooks.json.

1Binary location

Bundled in the apt / rpm / AUR package and installed automatically at /usr/bin/roamswitch-mcp. No separate download or build is needed (same for the Client and Server Edition).

/usr/bin/roamswitch-mcp

The same binary and setup steps work as-is on Server Edition (headless). See the "AI Agents / MCP Integration" chapter of the Linux Server operations manual for details.

2aFor Claude Desktop

Claude Desktop has no official Linux release. If you're using an unofficial build (e.g. claude-desktop-debian), add the following to "mcpServers" in ~/.config/Claude/claude_desktop_config.json and restart it.

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

2bFor Claude Code

Just run the following command once in your terminal.

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

2cFor OpenAI Codex CLI

Add the following to ~/.codex/config.toml, or run the command below in your 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).

{
  "mcp": {
    "roamswitch": {
      "type": "local",
      "command": ["/usr/bin/roamswitch-mcp"]
    }
  }
}

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"
    }
  }
}

* Note: If you encounter Hook Failure or telemetry errors in Antigravity CLI (agy), disable the hook by setting "enabled": false in ~/.gemini/config/plugins/.../hooks.json.

Available tools

Read-only tools (currently 33 on Mac / 38 on Linux — growing)

get_security_report

Runs an 18-point audit on Mac (FileVault, SIP, Gatekeeper, firewall, Wi-Fi encryption strength, ARP spoofing, exposed ports, etc.) or a 27-point client / 34-point server audit on Linux (kernel hardening, Docker socket and privileged-container protection, container runtime isolation, known vulnerabilities, etc.), and returns a score with improvement advice.

get_exposed_ports

Lists every port currently listening and, for any exposed externally, returns a detailed audit including known-risky-service detection (Redis, MongoDB, etc.). On Mac, it sends one HTTP GET per exposed port to 127.0.0.1 to check the headers.

get_guard_status

Returns active status of unknown port guard, ARP containment, USB guard, Bluetooth guard, Web/Mail download guard, DNS threat guard, and current security level.

audit_url_safety

Takes an email link or web URL to analyze phishing threats, Unicode homograph spoofing, deceptive subdomains, and high-risk TLDs completely on-device (Zero Telemetry).

get_app_help

Searches RoamSwitch's complete authoritative knowledge base covering all feature specifications, alert messages, settings, and troubleshooting on-device to return precise explanations and actionable advice.

audit_security_logs

Aggregates recent security logs (Mac: sudo auth failures, SSH brute-force attempts, Gatekeeper blocks, XProtect detections, etc. / Linux: sudo auth failures, SSH brute-force, firewall drops, AppArmor denials, ClamAV detections, etc.), automatically masks secrets like API keys and tokens, and also returns new-pattern detection (log templating) and frequency-anomaly (statistical spike) results. On Linux, if the journal could not be read (for example it timed out), the zero counts do not mean nothing happened; journalReadComplete becomes false and journalError gives the reason.

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 resources that AI clients can read directly into context (features, alert advice, settings, troubleshooting).

Other read-only tools

Tool	Platform	Summary
`audit_secrets`	Mac / Linux	Detects leaked API keys and private keys in text, a file, or a directory tree (matches are masked in the output).
`run_active_vuln_scan`	Mac / Linux	Non-destructive, 127.0.0.1-only active vulnerability verification. It never contacts another host, but it sends network requests, so it is disabled by default and requires an opt-in in the 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 items (`checkId`) from `get_security_report` against the current state and returns one verdict per item, `stillPresent` (still applies), `resolved` (fixed, or not applicable by design) or `inconclusive` (could not be determined), plus a language-independent reason code. Use it after a fix to confirm that the fix took effect. An item that could not be measured, for example because of missing privileges, a privileged helper that is not connected or an unreachable Docker, is never reported as safe and comes back as `inconclusive`. Omit `checkIds` to check every item (up to 50 ids on Mac and 64 on Linux; Linux also accepts `isServer`). On Mac, host_firewall, network_stealth_mode, gateway_arp_lock, malware_scanning, dns_threat_guard and usb_zero_trust are decided by RoamSwitch's in-app settings, so they reflect those settings and are not a re-measurement of the actual OS state. It is read-only, does not connect to external hosts, and neither repairs anything nor changes any setting. On Linux it sends nothing to the LAN either and only reads the gateway from local caches. On Mac, to look up the gateway's MAC address, it may send an ICMP ping, normally one (a few if the MAC cannot be resolved), to the gateway on the LAN.
`audit_mcp_configs`	Mac / Linux	Reads the MCP client configuration files (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI, plus .mcp.json and similar files in the registered project folders) and flags risky settings. It reports tools auto-approved without per-call confirmation (auto_approve), plaintext http:// servers on a non-loopback host, whether given in the url field or as a launch argument such as --server http://… (remote_plain_http), launch commands that are shell or interpreter one-liners (shell_wrapper), npx / uvx / docker run style launchers that fetch an unpinned package or image (unpinned_package_launcher), docker run with --privileged or with the Docker socket or root filesystem mounted (container_host_access), env entries that make the server load extra code at start-up, such as LD_PRELOAD or --require in NODE_OPTIONS (names matched without regard to case, values never returned; code_loading_env), entries pointing at HexStrike AI, an unauthenticated attack-tool backend (hexstrike), config files writable by group or others (world_writable_config),, Claude Code's enableAllProjectMcpServers switch (auto_trust_project_servers), and a config file that holds both a server that reads text other people wrote (web pages, mail, chat, issues) and a server that can run commands or write files, the pairing indirect prompt injection needs (recognised by well-known package names; it cannot see what a server's tools say; injection_exposure). It takes no arguments, is read-only and sends nothing to the network. It never returns env or header values, arguments or secrets, only server names, a command's basename, a URL host and, for a plain registry name, the package or image name. Files that could not be parsed are listed in unreadableFiles and were not audited.
`audit_agent_setup`	Mac / Linux	Reads the instruction files and skills you give AI agents (CLAUDE.md, commands, agents and skills under ~/.claude, plus ~/.codex, ~/.cursor/rules, ~/.gemini, ~/.agents, ~/.openclaw, and CLAUDE.md, AGENTS.md, .cursorrules and similar files in the registered project folders) and OpenClaw's openclaw.json, and flags risky content or settings. In instruction and skill files it reports sentences hidden in invisible Unicode tag characters (hidden_tag_characters), zero-width and bidirectional-control characters (invisible_characters), wording that tells an agent to ignore earlier instructions or hide things from the user (override_instruction), fetch-and-run such as curl … \| sh (remote_script_exec), decode-and-run (encoded_payload_exec), references to key and credential stores (credential_access) next to an upload or a drop-site service (credential_exfil_shape, exfil_endpoint), persistence set-up (persistence_instruction), compiled code inside a skill (skill_precompiled_code) and files others can write (agent_file_writable). Anything inside an HTML comment is rated higher, because a rendered page hides it. For OpenClaw it reports authentication switched off (openclaw_auth_disabled), a bind that is reachable from the network (openclaw_wide_bind), a token under 24 characters (openclaw_weak_token), a wildcard origin (openclaw_origin_wildcard), dangerously… switches turned on (openclaw_dangerous_flag), a proxy list that trusts everyone (openclaw_broad_trusted_proxy, openclaw_proxy_trust_loosened), DM or group policy open to anyone (openclaw_open_dm), full mDNS (openclaw_mdns_full), suppressed self-check findings (openclaw_audit_suppressed) and loose permissions (openclaw_loose_permissions). Every rule is deterministic: a hit means a person should read that line, not that the file is malicious. It takes no arguments, is read-only and sends nothing to the network. It never returns file contents or secrets (a token is reported by length only), only a rule name, a line number, a URL host and a configuration key path. Files that could not be read are listed in unreadableFiles and were not audited.
`run_package_cve_scan`	Mac / Linux	Checks installed packages (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) against a local CVE map. Sends no network traffic at all. On Linux, if the package list could not be read or timed out, it does not report "no findings"; complete becomes false and incompleteReason gives the reason (an unfinished result is not a clean result). On Ubuntu (20.04, 22.04, 24.04, 26.04) it uses Ubuntu's own data, matches by source package name and source version, and checks only CVEs of CVSS 7.0 or higher that Ubuntu has already shipped a fix for, so "no findings" does not mean there are no known CVEs. The result gains ecosystem and release, and each finding carries binary (the installed binary package name); fixes available only through Ubuntu Pro are marked proOnly. Ubuntu derivatives (Linux Mint, Pop!_OS and others) and unsupported releases return complete = false with the reason in incompleteReason, and are not switched to the Debian data.
`run_package_cve_scan_languages`	Mac / Linux	Checks dependency lockfiles for npm, PyPI, crates.io, RubyGems, Packagist, Go, and Maven against the same local CVE map. Sends no network traffic 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: nothing is executed and nothing is sent over the network. Each entry carries a reference flag for risky-looking patterns (such as curl\|sh), but this is an inventory, not a verdict on whether a package is malicious.
`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	This tool contacts the npm registry (registry.npmjs.org). It runs npm audit signatures to verify the registry signatures and provenance of installed packages. It is disabled by default and refuses to run until you enable it in the settings (Pro only on Mac).
`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	Returns whether general-purpose entropy-based ransomware detection is enabled and its recent entropy-burst incidents.
`get_honeytoken_status`	Mac	Returns whether the credential honeytoken guard is enabled and its recent access-detection events.
`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.
`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 record of process executions. On Mac it searches the eslogger-based log; on Linux, the exec recorder log (with a tamper-evident hash chain). You can filter by path, arguments and more, and the result also reports the recorder state and whether the log could be read. Pro only on Mac. The Linux log is root-only, so the MCP server has to run as root to read it.
`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 Port Anomaly Guard's baseline state, currently auto-blocked ports, and up to the 50 most recent incidents. The response explicitly notes that the currently-blocked ports are a present-tense snapshot with no timestamp, distinct from the timestamped incident history.
`get_ssh_guard_incidents`	Mac / Linux	Returns the state and history of the SSH brute-force guard: whether it bans or only detects (for example because another tool already guards sshd), the sources banned right now with the time left, and up to the 200 most recent records (a source was banned, was detected without a ban, or a login succeeded after a run of failures from the same source). The user names that were tried are not stored on Linux (only how many) and are returned sanitized, up to 5, on Mac. Mac also returns the recent SSH logins (source, user, method, key fingerprint). Read-only: no MCP tool lifts a ban. On Linux the ban list is readable by root only, so a non-root caller gets only the count. Linux: the Server Edition, and the Client Edition while sshd is running. Mac: Pro only.
`get_port_scan_incidents`	Linux	Returns the log of detected port scans (reconnaissance) against this device: each source IP that reached many distinct ports in a short window, how many ports it touched (with a sample), and whether it was also auto-blocked and for how long.
`get_runtime_threat_status`	Mac	Returns whether an XProtect malware conviction has air-gapped this Mac, and the incident that triggered it. Check this first to explain an active Air-Gap.
`verify_fim`	Linux	Re-hashes about 150 critical system files and compares them against the stored baseline to verify integrity. When run as root, the result also has an added field, `recentIntrusionContext`: for each recent change, the process that made it (account, executable, command) and the SSH login it belongs to (source, login time, authentication method), or why that could not be found.
`get_file_scan_guard_status`	Linux (Server)	Returns the File Scan Guard's (ClamAV) configuration and the state of the quarantine vault it feeds (a Server Edition tool; it does not report the Client Edition malware guard settings).
`get_ebpf_incidents`	Linux (Server)	Returns the eBPF Runtime Guard's current containment status and the incident history behind it. On the Server Edition each record also carries the time from detection to response in milliseconds (`detect_to_receive_ms`, `receive_to_action_ms`, `detect_to_action_ms`), and the result includes the state of the Falco heartbeat (`heartbeat`).
`get_resource_guard_incidents`	Linux (Server)	Returns the Resource Exhaustion / Process Anomaly Guard's history (memory leaks, crash loops) with a confidence tier (this guard belongs to the Server Edition; the Client Edition does not run it, so the result there is always empty).
`get_incident_timeline`	Mac / Linux	Correlates every guard's detections into one chronological timeline, with process ancestry and MITRE ATT&CK tags (experimental).
`get_network_history`	Mac	Records how many distinct gateway devices have answered for each remembered Wi-Fi network and when it was last seen, and flags other networks with suspiciously similar names (Evil Twin candidates). Also answers whether you've connected to a given network 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 Link Guard's (phishing / malicious-site blocking via DNS / TLS SNI / HTTP Host inspection) enabled state, mode (off / warn / block), allowlist, and block/warn events from the last 7 days.
`get_air_gap_status`	Linux (Client)	Returns whether emergency Air-Gap isolation (all traffic dropped) is active right now, why it triggered, time until auto-release, and every process currently frozen with SIGSTOP.
`get_sharing_services_status`	Linux (Client)	Returns the setting that auto-stops SSH, Samba, and screen sharing (GNOME Remote Desktop / VNC / xrdp) on untrusted networks, and the live state of the services it actually 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 USB storage guard and BadUSB keyboard guard settings (input is suppressed via evdev only — devices are never de-authorized at the kernel level), plus connected and pending-approval devices.
`get_fleet_status`	Linux	Returns this device's side of Fleet (organization-wide management, a feature in preparation for RoamSwitch Business): whether the device is enrolled, which policy version is applied, the check-in status, and so on. It never returns enrollment codes, tokens, keys or license data. Fleet has no remote command channel, so an administrator cannot isolate or operate this device.
`get_sensor_audit_results`	Mac / Linux	Returns the results of active audits requested from a paired RoamSwitch Sensor (a separate product that runs on your own hardware on the same LAN): pending, completed or failed. It adds the outside-in view of what can actually be reached, which is invisible from inside the device. Requesting an audit or pairing with a Sensor cannot be done through this tool.

Of the tools above, the ones that only read local state (quarantine vault, canary, port anomaly, runtime threat, notification history, incident timeline, network history, VPN / Link Guard / Air-Gap / sharing services / Bluetooth / USB guard status, etc.) keep working even while RoamSwitch has cut network access in response to a threat. Paired with a local LLM, you can investigate the cause on the spot during a cutoff.

Reason codes of verify_security_findings. Common to both platforms are failing (still applies), passing (no problem), not_applicable (not applicable here by design), not_verifiable (cannot be confirmed this way) and unknown_check_id (no such checkId). Only Mac returns helper_unavailable (the privileged helper is not connected), gateway_unknown (the gateway could not be identified), no_baseline (cannot be compared with the gateway MAC of a registered trusted network; if no trusted network is registered, the ARP check always returns this over MCP), not_measured (the port list has never been measured yet; this only occurs in the in-app report and normally not over MCP), location_unavailable (reading the Wi-Fi needs Location permission) and tool_failed (an OS command returned nothing, or its output could not settle enabled versus disabled, such as SIP reporting enabled (Custom Configuration)). Only Linux returns not_root (not running as root, so the data cannot be read), daemon_unknown (the daemon state is unavailable), tool_missing (a required command is missing), tool_timeout (an external command did not finish in time and was stopped), docker_unreachable (Docker cannot be reached) and unconfirmed (the check itself flagged its result as unconfirmed). On inconclusive the fix can be neither confirmed nor ruled out, so restore the missing privilege or connection and call the tool again.

The only tool that talks to an external host is run_npm_audit_signatures (the npm registry), which is opt-in and Pro-only on Mac. run_active_vuln_scan (off by default) only probes 127.0.0.1, and on Mac get_exposed_ports only sends one HTTP GET per exposed port to 127.0.0.1 to check the headers. To look up the gateway's MAC address, the Mac diagnostic tools may send an ICMP ping, normally one (a few if the MAC cannot be resolved), to the gateway on the LAN. On Linux, get_security_report and verify_security_findings send nothing to the LAN and only read the gateway from local caches (other tools that resolve the gateway's MAC afresh, such as get_guard_status, may send one ping).

Practical Use Cases

Real-World Prompts for Dev & Daily Workflows

Explore realistic prompts and AI responses for auditing dev server ports, checking public Wi-Fi security, verifying suspicious links, and more. Copy prompts directly into your AI.

🛠️

Local Server & DB Port Exposure Audit

Web Dev / Docker

When launching Next.js, Vite, Python, Docker, Redis, etc., have your AI audit whether ports are inadvertently exposed to the local network on 0.0.0.0.

💬 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 Findings:
• 🚨 Port 3000 (node / Next.js): Exposed externally on 0.0.0.0:3000
• 🚨 Port 6379 (redis-server): Exposed externally on 0.0.0.0:6379 (unauthenticated; accessible by other devices on same Wi-Fi)
• ✅ Port 5432 (postgres): Bound to 127.0.0.1:5432 (localhost only / safe)
💡 Remediation: Set bind 127.0.0.1 in Redis configuration, and launch 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 cafe or hotel, have AI perform a comprehensive posture check to verify if firewall, stealth mode, and ARP defense are active.

💬 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 Security Diagnostic Summary:
• 🛡️ Overall Score: 88 / 100 (Grade: A-)
• 📡 Network Status: Untrusted Network (Public mode / packet filter active)
• ✅ Firewall / Stealth Mode: Enabled (blocking external probe packets)
• ✅ ARP Spoofing Auto-Containment: Enabled (auto-isolates on interception detection)
• ⚠️ Action Item: FileVault disk encryption is disabled. Recommended to enable it in System Settings.

✉️

Inspecting Suspicious Email & Chat Links

Phishing Defense / URL Audit

Have AI instantly inspect URLs from suspicious emails or Slack/Discord DMs entirely on-device without sending the link to external servers (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 Safety Audit (Fully Local Inspection):
• 🚨 Risk Level: Dangerous (Safety Score: 8/100)
• ❌ Brand Spoofing Subdomain: Pretending to be apple.com, but actual domain is login-auth-verify.xyz.
• ❌ High-Risk TLD: .xyz is frequently associated with disposable phishing campaigns.
• 🔒 Zero Telemetry: Inspected locally on your Mac with zero external data transmission.
• 🛑 Recommendation: Do not click the link. Delete and report the email immediately.

🤖

Autonomous Security Safeguard during Coding

Agentic AI Workflows

When delegating fullstack tasks to Claude Code or Antigravity, let the agent use MCP tools as autonomous safeguards to verify that no unauthorized ports were opened.

💬 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

Autonomous AI Execution Summary:
1. Launched Fastify backend on port 8080.
2. 🔍 RoamSwitch MCP Verification: Executed get_exposed_ports and confirmed port is bound strictly to 127.0.0.1:8080 with no LAN exposure.
3. Environment verified secure. Proceeding with integration tests.

📋

Daily Security Check & Markdown Report Export

Compliance & Reporting

Generate a clean, structured Markdown security status report for IT compliance, company policy audits, or personal daily logs.

💬 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

Generated Markdown Report:

## 🛡️ Mac Security Health Report (2026-08-28)
- Score: 96 / 100 (Grade: A+)
- Core Defenses:
  • FileVault: ✅ Enabled (APFS Encrypted)
  • SIP: ✅ Enabled
  • Firewall / Stealth Mode: ✅ Enabled
  • ARP Spoofing Auto-Containment: ✅ Enabled
  • DNS Threat Guard: ✅ Enabled (Quad9 Secure DNS)
- Action Items: None (Mac is in excellent security posture)

🛡️

Verifying USB, Bluetooth & Download Guards

Device & Physical Defense

Confirm active status for all RoamSwitch real-time guard features, including unknown USB storage alerts, Bluetooth monitoring, and download protection.

💬 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

RoamSwitch Guard Status:
• 🛡️ Active Level: Balanced (Standard Protection)
• ✅ USB Storage Guard: Active (alerts/blocks unapproved USB connections)
• ✅ Bluetooth Guard: Active (monitors proximity of unpaired devices)
• ✅ Web/Mail Download Guard: Active (auto-scans quarantined files via ClamAV)
• ✅ DNS Threat Guard: Active (blocks malicious C2 and phishing domains)

💡

Ask About Features, App Usage, and Alert Messages

App Guide / Alert Advice

Consult the AI about any notification, warning, or fine-grained technical feature (PF packet filter, FSEvents, ClamAV quarantine, USB guard, etc.) and receive verified explanations from the built-in knowledge base.

💬 Pattern A: Dev Port Auto-Shield & Safe Config (Next.js / Web Dev)

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 from RoamSwitch Knowledge Base:
• 🚪 Reason: Your dev server launched on 0.0.0.0 (public to LAN). RoamSwitch blocked incoming external connections while preserving localhost.
• ⚙️ Remediation:
1. Recommended (Localhost only): Launch with npm run dev -- -H 127.0.0.1 to prevent exposing the port.
2. LAN sharing: Whitelist port 3000 via RoamSwitch menu > 'Port Audit'.

💬 Pattern B: Post-Containment Safety Audit (After switching to tethering)

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 from RoamSwitch Knowledge Base:
• 🔍 Incident Analysis: A rogue host on the Wi-Fi was broadcasting spoofed ARP packets to impersonate the gateway and intercept/modify network traffic (Man-In-The-Middle attack).
• 🛡️ Automated Defense: RoamSwitch's ARP containment triggered instantly, isolating the interface to prevent packet eavesdropping.
• 🛑 Recommended Action: Do not reconnect to that public Wi-Fi. Continue working securely on tethering. Review security logs under 'Log Audit'.

💬 Pattern C: USB Auto-Ejection & Safe Whitelist Registration

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 from RoamSwitch Knowledge Base:
• 🔌 Reason for Ejection: Automatically unmounted to prevent unauthorized data exfiltration and BadUSB firmware attacks.
• ⚙️ Registration Steps: 1. Open RoamSwitch 'Settings' from the menu bar → 2. Select 'USB Storage Guard' → 3. Click 'Add from Connected Devices' and select your drive → 4. Set permission to 'Read-Only (Recommended)' and save. It will mount safely on next connection.

💬 Pattern D: Helper Disconnected & Daemon Recovery Guidance

The menu bar displays '⚠️ Helper Not Connected'. How can I restore it?

⚡ Tool: get_app_help / Resource: roamswitch://docs/troubleshooting

Answer from RoamSwitch Knowledge Base:
• ⚠️ Cause: XPC communication with the privileged background daemon RoamSwitchHelper (which manages packet filtering) is temporarily disrupted.
• 🛠️ Recovery Steps:
  1. Open Terminal and restart the helper daemon:
    sudo killall RoamSwitchHelper
  2. Relaunch the RoamSwitch app.
  3. In macOS 'System Settings' > 'General' > 'Login Items & Extensions', ensure RoamSwitchHelper is enabled.

🧯

Offline triage with a local LLM + MCP after an Air-Gap emergency lockdown

Incident Response / Local LLM Triage

When Air-Gap (emergency network lockdown) triggers — say, on ransomware detection — it also cuts off cloud AI clients like Claude Desktop. But RoamSwitch's MCP server keeps working, since it only talks over a local process pipe; pair it with a local LLM (e.g. via Ollama) and you can keep diagnosing with zero network access. Log anomaly detection, tamper detection, and known-CVE matching are all fully local, so this is exactly the moment they're built for: when the network itself is gone.

💬 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 triage results (zero network activity):
• 🐛 Canary triggered: Encryption of /var/www/decoy_invoice.pdf detected at 14:32:07; process suspicious_enc (PID 8823) was immediately frozen and isolated
• 🔌 Port monitoring (Port Anomaly Guard): No new auto-blocked listeners in the incident history — the canary trigger appears to be the only entry point, with no additional backdoor ports opened
• 📜 Log correlation (anomaly detection): A spike in sshd auth failures starting 12 minutes before the trigger (frequency spike detected, Z-score 5.2) — a possible entry point
• 🔒 Tamper detection (FIM): No tampering found across ~150 critical system paths — no sign the breach reached the system layer
• 📦 Known-CVE check: Cross-referenced against the local CVE map — no critical known vulnerabilities in the affected packages
💡 Recommended action: The breach is likely confined to the web root. Before restoring from backup, individually check the other files in that directory as well.

FAQ

About MCP integration

Q. Does it really never communicate externally?

A. Correct. The MCP server is a local process launched directly by your AI client over standard I/O (stdio), and it never sends telemetry. Diagnostic results are computed on the spot, on this Mac / Linux machine. The only tool that talks to an external host is run_npm_audit_signatures (the npm registry), which is opt-in and Pro-only on Mac. run_active_vuln_scan (off by default) only probes 127.0.0.1, and on Mac get_exposed_ports only sends one HTTP GET per exposed port to 127.0.0.1 to check the headers. To look up the gateway's MAC address, the Mac diagnostic tools may send an ICMP ping, normally one (a few if the MAC cannot be resolved), to the gateway on the LAN. On Linux, get_security_report and verify_security_findings send nothing to the LAN and only read the gateway from local caches (other tools that resolve the gateway's MAC afresh, such as get_guard_status, may send one ping).

Q. Can I use it without the Pro version?

A. On Linux, every tool is available at no cost. On the free version of the Mac app most tools work too, but four are Pro-only and return an error when Pro is not active: get_ransomware_recovery_snapshots, search_exec_events, get_process_tree and run_npm_audit_signatures. Also, whether each auto-guard is actually active depends on the Pro license status too, so the tools can only confirm the toggle state in Settings.

Q. Which AI clients are supported?

A. Any client that supports the MCP (Model Context Protocol) stdio transport should generally work, even beyond the ones listed above. Verified 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 from external plugins (such as Google Cloud telemetry) in Antigravity may block tool execution. Open ~/.gemini/config/plugins/.../hooks.json and set "enabled": false to disable the hook.

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

A. Yes, if you are using a local LLM via tools like OpenCode (with Ollama or LM Studio), everything runs 100% on-device and queries work seamlessly even during emergency network air-gap containment. If you are using cloud LLMs (such as Claude API), switch to a safe connection like mobile tethering before querying.