Use VisualEther with Any MCP Client

VisualEther ships a Model Context Protocol (MCP) server so an AI assistant can analyze your captures — detect protocols, generate templates, render sequence diagrams, and answer "why did this fail?" in plain English. The server is client-agnostic: it speaks standard MCP over stdio, so any MCP-capable client can drive it, not just Claude Code.

Every client launches the server the same way:

command:  <path to visualether>
args:     ["mcp", "server"]

Only the config file and the wrapper key change from one client to the next. This page has a ready-to-paste block for each.

Claude Code users — skip this page. Claude Code has a one-command installer: run visualether mcp install --scope user (or --scope project) and restart Claude Code.

About client support. VisualEther's MCP server is built and tested against Claude Code. Because the server speaks standard MCP over stdio, it should work with any compliant client.

Jump to your client

Step 1 — find your VisualEther path

Every config below needs the absolute path to the visualether executable. The CLI prints it for you — run:

visualether mcp config

It fills in your executable's own resolved path and the exact command / args to drop into any client block below:

VisualEther MCP server

  command: /usr/local/bin/visualether
  args:    ["mcp", "server"]

Claude Code:   visualether mcp install --scope user   (or --scope project)
Other clients: https://www.eventhelix.com/visualether/mcp-clients/

Use the printed command value in the blocks below; args is always ["mcp", "server"]. On Windows, either escape the backslashes in JSON (C:\\Program Files\\VisualEther\\visualether.exe) or use forward slashes.

Step 2 — add the server to your client

Codex CLI

Codex uses TOML, not JSON. For a global setup, edit ~/.codex/config.toml. For a repo-only setup, use <project>/.codex/config.toml; Codex loads project config only after the project is trusted. The Codex CLI and IDE extension share this config.

[mcp_servers.visualether]
command = "/path/to/visualether"
args = ["mcp", "server"]

Or let Codex write the global config entry for you:

codex mcp add visualether -- /path/to/visualether mcp server

Optional Codex MCP settings can live in the same table:

[mcp_servers.visualether]
command = "/path/to/visualether"
args = ["mcp", "server"]
startup_timeout_sec = 20
tool_timeout_sec = 300

[mcp_servers.visualether.env]
VISUALETHER_TSHARK_PATH = "/path/to/tshark"

After restarting Codex, run /mcp in the Codex TUI to confirm the visualether server and tools are active.

When asking Codex to generate diagrams, keep the request high level and let the VisualEther MCP instructions drive the workflow. Codex reads the server's MCP instructions, including the recommended analyze_capture -> explore / extract_sessions flow, default auto_open: true, shared <pcap-dir>/output layout, and NDJSON inspection guidance.

Good prompt: "Analyze capture.pcap with VisualEther, generate both explore and session-level diagrams under the capture's output directory, and review the generated NDJSON for flow and protocol issues."

If you want a self-contained VisualEther project, say so explicitly. Codex should then create or update explore.fxt.xml, sessions.fxt.xml, and hosts.txt next to the capture, then call materialize_config to validate the FXTs and write visualether.toml plus .gitignore.

Project prompt: "Analyze the pcap in this directory with VisualEther. Generate explore and session-level diagrams, and also create or update explore.fxt.xml, sessions.fxt.xml, hosts.txt, and visualether.toml."

Prefer the MCP tools over asking Codex to run visualether CLI commands directly. If you do need Codex to run the VisualEther CLI — for example visualether serve list — approve running that command outside Codex's sandbox. The sandbox may run under a restricted helper account that cannot read your per-user license file or interact with the already-running serve registry.

Antigravity

Edit the global config file mcp_config.json:

Key: mcpServers.

{
  "mcpServers": {
    "visualether": { "command": "/path/to/visualether", "args": ["mcp", "server"] }
  }
}

Antigravity is highly autonomous and can navigate the entire VisualEther analysis workflow without step-by-step guidance. For the best results, we recommend using the Gemini 3.1 Pro model. Simply state your high-level goal and point it to the relevant files (like the PCAP and any keylogs).

Because Antigravity can read the MCP schemas, it will naturally discover the correct workflow: running analyze_capture to detect protocols, picking the recommended built-in sample (like http3), and then executing both explore and extract_sessions tools. It will also seamlessly handle things like passing your keylog files down to Wireshark via tshark_args.

Good prompt for diagram generation: "Please analyze the pcap file and keys in this directory to generate explore and session level diagrams. Please use the keys file to decode."

For investigating specific network behavior, Antigravity excels at diving deep into the data. Instead of making it guess or run raw CLI commands, ask direct questions about the traffic. Antigravity will use the generated .ndjson output or the query_fields MCP tool to answer complex questions by extracting precise Wireshark fields (like expert info or relative frame timings).

Investigatory prompts:

To prevent Antigravity from using the VisualEther CLI (and instead strictly rely on MCP tools and the provided sample paths), you can create an AGENTS.md file in your workspace (.agents/AGENTS.md) or globally (~/.gemini/config/AGENTS.md on macOS/Linux, %USERPROFILE%\.gemini\config\AGENTS.md on Windows) with the following rule:

# VisualEther Usage Guidelines
When using the VisualEther MCP server to generate diagrams:
1. NEVER use the `visualether` CLI commands (like `new` or `init`) in the terminal to create projects.
2. The `explore` and `extract_sessions` tools support sample-relative paths directly. Pass the relative path (e.g., `ldap/explore.fxt.xml`) straight into the `fxt_file` parameter.
3. If you need to extend a template to cover missing protocols, locate the base template using the `samples_root` path provided by `analyze_capture`, copy its contents to a local file, modify it, and use your local file for generation.

Cursor

Edit ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (project-only). Key: mcpServers.

{
  "mcpServers": {
    "visualether": { "command": "/path/to/visualether", "args": ["mcp", "server"] }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json). Key: mcpServers. Restart Windsurf after saving.

{
  "mcpServers": {
    "visualether": { "command": "/path/to/visualether", "args": ["mcp", "server"] }
  }
}

VS Code (GitHub Copilot)

Edit .vscode/mcp.json in your workspace, or add it to your user profile. Note the key is servers, not mcpServers.

{
  "servers": {
    "visualether": { "type": "stdio", "command": "/path/to/visualether", "args": ["mcp", "server"] }
  }
}

Claude Desktop

Open Settings → Developer → Edit Config, or edit the file directly:

Key: mcpServers. Restart Claude Desktop after saving.

{
  "mcpServers": {
    "visualether": { "command": "/path/to/visualether", "args": ["mcp", "server"] }
  }
}

Zed

Edit settings.json (open the command palette → zed: open settings). Key: context_servers.

{
  "context_servers": {
    "visualether": { "command": "/path/to/visualether", "args": ["mcp", "server"], "env": {} }
  }
}

Zed's assistant can drive the full VisualEther workflow — protocol detection, template selection, explore and session-level diagram generation, and follow-up field queries — without step-by-step guidance. We have tested the MCP server with DeepSeek V4 Pro in Zed.

Important: Zed does not appear to surface the MCP server's instructions to the agent. VisualEther's server instructions carry the Quick Start workflow, behavioral defaults (output directory conventions, auto_open, live-reload, hosts files, axis, timestamps), and pointers to FXT_SYNTAX_REFERENCE.md and MCP_USAGE_GUIDE.md. When that block isn't passed through, the agent never sees it. The AGENTS.md below restores the critical guidance the agent would otherwise miss.

State your high-level goal and point the assistant at the capture (and any keylog/keys files); it will discover the correct workflow from the MCP schemas, pass the keys down to Wireshark via tshark_args, and render both explore and session-level diagrams under the capture's output directory.

Good prompt for diagram generation: "Please analyze the pcap file and keys in this directory to generate explore and session level diagrams."

For investigating specific network behavior, ask direct questions about the traffic. Zed's assistant will use the generated .ndjson output or the query_fields MCP tool to answer by extracting precise Wireshark fields (such as expert info, packet numbers, or relative frame timings).

Investigatory prompts:

Zed reads AGENTS.md from the project root and from ~/.agents/ for global instructions. When the server instructions aren't passed through, add the following AGENTS.md to every VisualEther project (or globally at ~/.agents/AGENTS.md) to restore the workflow guidance, behavioral defaults, and document pointers the agent needs:

# VisualEther Usage Guidelines

## Quick Start workflow
1. Check the PCAP directory for existing `explore.fxt.xml` / `sessions.fxt.xml`.
   If present and covering the target protocols, skip to step 3.
2. Run `analyze_capture` to detect protocols and get a suggested template.
3. Run `explore` for a full-capture diagram; run `extract_sessions` for
   per-session diagrams grouped by outcome.
4. Prefer MCP tools over the `visualether` CLI — the tools coordinate output
   layout, the shared auto-spawned serve, browser opening, and live-reload.

## Behavioral defaults
- **`output_dir`**: always pass `<pcap-dir>/output` exactly — never an
  `explore`/`sessions` subdir. Both tools share the auto-appended
  `output/<stem>/` so the Capture Atlas lists the capture once.
- **`auto_open`**: leave at default `true`. The serve is single-instance and
  reused across calls, so redundant browser opens are skipped automatically.
- **Live-reload**: viewers reload shortly after regeneration; don't tell the
  user to refresh.
- **Hosts files**: skip generation for large captures (>50 MB or >20
  endpoints). Use `extract_endpoints` (not `extract_fields`), save as
  `hosts.txt`, use child.parent dot notation (`AMF.5GC`, not `Client.gRPC`).
- **`axis`**: default `ip`; use `port` for loopback/localhost traffic.
- **Timestamps**: pass `timestamp_format` (`absolute` | `relative-first` |
  `relative-previous`) to `explore` / `extract_sessions`. Use
  `relative-first` for time-since-first-message — it resets per session in
  `extract_sessions`. Do NOT add a `frame.time_relative` FXT param instead.

## FXT authoring (when no .fxt.xml exists)
- `analyze_capture` returns `samples_root` (absolute) and per-template
  `template_path` (relative). Join them, read the sample FXTs, combine and
  adapt, write `explore.fxt.xml` / `sessions.fxt.xml` into the pcap directory.
- Do NOT run `visualether new` — `new` is for CLI users.
- When no built-in sample covers the protocol: `extract_fields` (with
  protocols filter) -> `extract_endpoints` -> author from domain knowledge ->
  `validate_fxt`.
- After writing FXTs, call `materialize_config` to validate them and write
  `visualether.toml` + `.gitignore`.

## Read the reference docs before editing templates
Before authoring or modifying any FXT, read `FXT_SYNTAX_REFERENCE.md` and
`MCP_USAGE_GUIDE.md` (bundled under the VisualEther `documents/` directory).
`FXT_SYNTAX_REFERENCE.md` is the authoritative reference for FXT elements,
attributes, regex, session lifecycle, and the `required="true"`
param-gating pattern. `MCP_USAGE_GUIDE.md` covers workflows, hosts files,
batch processing, troubleshooting, DLT_USER, encapsulation, validate_fxt
codes, and tshark options.

## Validate after every FXT edit
After editing an FXT, validate it against the PCAP with the `validate_fxt`
tool before regenerating diagrams. Fix and re-validate until the summary
reads "FXT valid" with full packet coverage.

## Use absolute paths in tshark_args
When passing decryption keys via `tshark_args` (e.g. a Kerberos keytab), use
the absolute path to the key file. A relative path fails because tshark
resolves it relative to its own working directory, not the project root.

Step 3 — verify it works

Restart your client, then ask the assistant to analyze a capture — for example, "Analyze capture.pcap with VisualEther." The assistant should call VisualEther's analyze_capture and explore tools and produce a sequence diagram. If the tools don't appear, double-check the executable path and that you saved the config in the right file.

Optional environment variables

Any client's config accepts an env block (a nested [mcp_servers.visualether.env] table in Codex's TOML). The VisualEther server reads:

VariablePurpose
VISUALETHER_TSHARK_PATHPath to tshark when it is not on the system PATH.
VISUALETHER_HOSTS_FILEDefault hosts file for IP-to-hostname substitution.
VISUALETHER_FONTS_DIRFont directory for non-Latin scripts (CJK, Devanagari, Arabic, Hebrew) in PDF output.
VISUALETHER_LICENSE_FILEPath to a license file in a non-standard location.

Notes

Start 45-day trial Download — free Buy a license