network-xray
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NX_MCP_PATH | No | The lab state the tools read when the client gives no path: a saved state JSON file (or xray-states.js), or its folder. The server reads only under that folder. To try it here, use the demo lab in the image: /app/demo/bgp-lp/frameB.json (BGP LocPref, r2 wins) or /app/demo/bgp-lp/frameA.json (r3 wins). | /app/demo/bgp-lp/frameB.json |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only questions about a network-xray lab from saved state files. No router is contacted.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| lab_stateA | Read a network-xray lab state (read-only) and summarize it. Starts with |
| why_best_pathA | For one node and prefix, give the BGP best path and the reason stored in the data (FRR selectionReason, or the IOS-XE collector's derived reason). If the data has no reason, reason is null and a note says so; nothing is guessed. Read-only. |
| list_routersA | List the routers in a network-xray lab state and which protocols have state for each (ospf: OSPF neighbors or LSDB in the data; bgp: BGP neighbors or BGP routes), whether a routing table was collected, and row counts. Read-only. |
| ospf_neighborsC | Starts with |
| ospf_interfacesB | Starts with |
| bgp_neighborsA | Starts with |
| route_lookupA | Look up a destination address in one router's collected routing table (installed rows only) by longest prefix match: the matching route, its protocol, next hop and outgoing interface (all next hops for ECMP). next_hop is null for a directly connected route; route is null with a note when nothing matches. A recursive next hop carries resolved_via (what the router resolved it through; via_mgmt when that is the lab's management network, i.e. not reachable inside the lab topology) and a note says so. When the data has the OSPF database (collected with network-xray 1.4 or later), the answer starts with |
| why_pathA | Why one router selected its BGP path to a prefix: the selected path, the other candidates with their attributes, the deciding step, and where that reason came from: reason_source "device" when the router reported it (FRR selectionReason), "derived" when the collector worked it out from what the router printed (Cisco IOS-XE prints no reason), "comparison" when network-xray inferred it by comparing the attributes in the data (Weight, LocPrf, AS-Path, Origin, MED), or null with a note when neither says. A bare address is matched to the longest BGP prefix that contains it. Read-only. |
| state_diffA | What changed from a baseline state you kept to the state now, heaviest first: routers gone or not read, interfaces down, OSPF adjacencies lost, OSPF interface values both ends must share that changed, BGP sessions down, best paths that moved (with the router's reason), routes removed or moved (with originated_by: the router where that prefix is directly connected), then what came back or was added. none is true when nothing changed. Uptimes, counters and the management network are not compared. The baseline is whatever path you pass as before (a state you saved, or collect's previous). Read-only. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 9 tools
Most tools target distinct resources, but why_best_path and why_path clearly overlap: why_path returns the selected path plus candidates, deciding step, and reason source, which subsumes why_best_path's 'best path plus reason' output. An agent can easily pick the wrong one of the pair. Additionally, lab_state, ospf_neighbors, and ospf_interfaces all lead with the same 'wrong' block, causing partial output overlap even though their primary payloads differ.
All names are snake_case, which is good, and protocol-scoped tools (ospf_, bgp_) are consistently prefixed. However, the verb convention is mixed: list_routers and route_lookup lead with a verb, why_path and why_best_path use a why_ prefix, while lab_state, state_diff, ospf_neighbors, and ospf_interfaces carry no verb at all. The set is readable but not a predictable pattern.
Nine tools is well-scoped for a read-only network lab diagnostic server. Each tool covers a distinct slice of the diagnostic surface (state summary, diffs, OSPF, BGP, routing table, path reasoning) without redundancy bloating the count.
The surface covers the core diagnostic workflow well: state snapshot, routers, OSPF neighbor/interface health with mismatch detection, BGP sessions, route lookup with longest-prefix match, path selection reasoning, and baseline diffing. Minor gaps exist, such as no dedicated LSDB inspection tool and no general BGP route-table listing (only per-prefix reasoning), but these are workable around.