Topolograph BGP Topology Analysis
pyats-routing, pyats-junos-routing and multivendor-device-query each
read one live device's BGP table. This one reasons over BGP topology
Topolograph has already collected via BMP — speakers, sessions, the route
table across every reporting peer, VRF/VPN placement, and whether that BGP
epoch actually corresponds to a stored IGP graph.
It answers "what does BGP believe the topology and route state are" — not
"what is in this router's BGP table right now."
Remote, read-only
Same server as topolograph-igp-analysis (spec 119): topolograph-mcp is a
remote HTTP MCP registered in config/openclaw.json, no local server,
fronting your own Topolograph instance (TOPOLOGRAPH_MCP_URL, default
https://topolograph.com/mcp), bearer TOPOLOGRAPH_API_TOKEN. No
second credential — if the IGP skill already works, this one does too.
The server runs with TOPOLOGRAPH_MCP_READ_ONLY=true: mutation tools are
absent from tools/list. None of the 14 BGP tools mutate anything.
Requires Topolograph >= 2.69 and a topolograph-mcp-server build that
includes the BGP tool surface (upstream PR #1). Older instances will list
these tools but every call 404s or returns empty — check TOOLS.md for the
version note before assuming a live instance is broken.
Client-side allowlist
defenseclaw tool allow topolograph-mcp list_bgp_graphs
defenseclaw tool allow topolograph-mcp get_bgp_graph
defenseclaw tool allow topolograph-mcp list_bgp_nodes
defenseclaw tool allow topolograph-mcp list_bgp_sessions
defenseclaw tool allow topolograph-mcp search_bgp_routes
defenseclaw tool allow topolograph-mcp get_bgp_node_route_summary
defenseclaw tool allow topolograph-mcp get_bgp_route_state
defenseclaw tool allow topolograph-mcp compare_bgp_routes
defenseclaw tool allow topolograph-mcp get_bgp_events_timeline
defenseclaw tool allow topolograph-mcp list_bgp_bindings
defenseclaw tool allow topolograph-mcp get_bgp_binding
defenseclaw tool allow topolograph-mcp resolve_route
defenseclaw tool allow topolograph-mcp get_vrf_inventory
defenseclaw tool allow topolograph-mcp list_vpn_routers
Same belt-and-braces note as the IGP skill: the server already hides
mutation tools; this allowlist is the client-side floor in case a
misconfigured instance widens the surface.
Tools
| Tool |
Answers |
list_bgp_graphs / get_bgp_graph |
Which BGP epochs (BMP collection cycles) exist; the full graph for one. Start here to get a bgp_graph_time. |
list_bgp_nodes |
BGP speakers in an epoch — role, ASN, route-reflector/PE/core device role. |
list_bgp_sessions |
Peering sessions — eBGP/iBGP, families, policy direction, relation to the IGP topology. |
search_bgp_routes |
The route table, whole-graph or scoped to one speaker's resolved RIB view — prefix, community, AS-path, RT, and 15+ other filters. |
get_bgp_node_route_summary |
One speaker's route totals: per-RIB-tag histogram, Adj-RIB-Out count. |
get_bgp_route_state |
Point-in-time route state as of a timestamp. |
compare_bgp_routes |
What changed (added/withdrawn/changed) between two instants, optionally scoped to one router, across a collector restart. |
get_bgp_events_timeline |
BGP session/route monitoring events. |
list_bgp_bindings / get_bgp_binding |
Whether a BGP epoch's speaker set is matched to a stored IGP graph, and how confidently (source_coverage, matched router IDs). |
resolve_route |
Resolve a destination end to end, including a BGP/VPN/MPLS handoff — not just the IGP shortest path. |
get_vrf_inventory / list_vpn_routers |
VRF names/RDs/route-targets per router; which routers are VPN-PE candidates for resolve_route. |
Boundary — when to use something else
| Question |
Skill |
| "What BGP speakers/sessions/routes does this topology have?" |
this skill |
| "What is in this router's BGP table / VRF right now?" |
pyats-routing, pyats-junos-routing, multivendor-device-query |
| "What does the IGP topology look like / what if this link fails?" |
topolograph-igp-analysis |
| "Is this BGP epoch actually the same network as that IGP graph?" |
this skill — list_bgp_bindings |
| "Push a policy / session change" |
device-write path, gated — never here |
Never
- Never present
compare_bgp_routes or resolve_route output as something
observed on the wire this second — both describe a stored epoch. Report
how old the bgp_graph_time is.
- Never treat a
bound binding state as permanent — list_bgp_bindings
reflects one BGP epoch matched against one IGP graph; a later epoch can
have a different source_coverage, or needs_mapping state.
- Never report an empty result from any of these 14 tools as "no BGP data
exists" without first checking
TOOLS.md's version note — every one of
them silently returned empty on Topolograph instances predating the
auth fix in v2.69.1/v2.69.2 (spec 120 research R2), which looks identical
to "no data" from the caller's side.
1---2name: topolograph-bgp-analysis3description: Reason over BGP topology as a whole -- speakers, peering sessions, the route table, VRF/VPN membership, and whether a BGP epoch is bound to a stored IGP graph. Use when the question is about what the BGP control plane believes (learned routes, session state, VRF placement, BGP-to-IGP correlation) rather than what one live device's BGP table currently shows. Read-only.4license: Apache-2.05---6
7# Topolograph BGP Topology Analysis
8
9`pyats-routing`, `pyats-junos-routing` and `multivendor-device-query` each
10read **one live device's** BGP table. This one reasons over BGP topology
11Topolograph has already collected via BMP — speakers, sessions, the route
12table across every reporting peer, VRF/VPN placement, and whether that BGP
13epoch actually corresponds to a stored IGP graph.
14
15It answers "what does BGP believe the topology and route state are" — not
16"what is in this router's BGP table right now."
17
18## Remote, read-only
19
20Same server as `topolograph-igp-analysis` (spec 119): `topolograph-mcp` is a
21remote HTTP MCP registered in `config/openclaw.json`, no local server,
22fronting **your own** Topolograph instance (`TOPOLOGRAPH_MCP_URL`, default
23`https://topolograph.com/mcp`), bearer `TOPOLOGRAPH_API_TOKEN`. No
24second credential — if the IGP skill already works, this one does too.
25
26The server runs with `TOPOLOGRAPH_MCP_READ_ONLY=true`: mutation tools are
27absent from `tools/list`. None of the 14 BGP tools mutate anything.
28
29**Requires Topolograph >= 2.69** and a `topolograph-mcp-server` build that
30includes the BGP tool surface (upstream PR #1). Older instances will list
31these tools but every call 404s or returns empty — check `TOOLS.md` for the
32version note before assuming a live instance is broken.
33
34## Client-side allowlist
35
36```bash
37defenseclaw tool allow topolograph-mcp list_bgp_graphs
38defenseclaw tool allow topolograph-mcp get_bgp_graph
39defenseclaw tool allow topolograph-mcp list_bgp_nodes
40defenseclaw tool allow topolograph-mcp list_bgp_sessions
41defenseclaw tool allow topolograph-mcp search_bgp_routes
42defenseclaw tool allow topolograph-mcp get_bgp_node_route_summary
43defenseclaw tool allow topolograph-mcp get_bgp_route_state
44defenseclaw tool allow topolograph-mcp compare_bgp_routes
45defenseclaw tool allow topolograph-mcp get_bgp_events_timeline
46defenseclaw tool allow topolograph-mcp list_bgp_bindings
47defenseclaw tool allow topolograph-mcp get_bgp_binding
48defenseclaw tool allow topolograph-mcp resolve_route
49defenseclaw tool allow topolograph-mcp get_vrf_inventory
50defenseclaw tool allow topolograph-mcp list_vpn_routers
51```
52
53Same belt-and-braces note as the IGP skill: the server already hides
54mutation tools; this allowlist is the client-side floor in case a
55misconfigured instance widens the surface.
56
57## Tools
58
59| Tool | Answers |
60|---|---|
61| `list_bgp_graphs` / `get_bgp_graph` | Which BGP epochs (BMP collection cycles) exist; the full graph for one. Start here to get a `bgp_graph_time`. |
62| `list_bgp_nodes` | BGP speakers in an epoch — role, ASN, route-reflector/PE/core device role. |
63| `list_bgp_sessions` | Peering sessions — eBGP/iBGP, families, policy direction, relation to the IGP topology. |
64| `search_bgp_routes` | The route table, whole-graph or scoped to one speaker's resolved RIB view — prefix, community, AS-path, RT, and 15+ other filters. |
65| `get_bgp_node_route_summary` | One speaker's route totals: per-RIB-tag histogram, Adj-RIB-Out count. |
66| `get_bgp_route_state` | Point-in-time route state as of a timestamp. |
67| `compare_bgp_routes` | What changed (added/withdrawn/changed) between two instants, optionally scoped to one router, across a collector restart. |
68| `get_bgp_events_timeline` | BGP session/route monitoring events. |
69| `list_bgp_bindings` / `get_bgp_binding` | Whether a BGP epoch's speaker set is matched to a stored IGP graph, and how confidently (`source_coverage`, matched router IDs). |
70| `resolve_route` | Resolve a destination end to end, including a BGP/VPN/MPLS handoff — not just the IGP shortest path. |
71| `get_vrf_inventory` / `list_vpn_routers` | VRF names/RDs/route-targets per router; which routers are VPN-PE candidates for `resolve_route`. |
72
73## Boundary — when to use something else
74
75| Question | Skill |
76|---|---|
77| "What BGP speakers/sessions/routes does this topology have?" | **this skill** |
78| "What is in *this router's* BGP table / VRF right now?" | `pyats-routing`, `pyats-junos-routing`, `multivendor-device-query` |
79| "What does the IGP topology look like / what if this link fails?" | `topolograph-igp-analysis` |
80| "Is this BGP epoch actually the same network as that IGP graph?" | **this skill** — `list_bgp_bindings` |
81| "Push a policy / session change" | device-write path, gated — never here |
82
83## Never
84
85- Never present `compare_bgp_routes` or `resolve_route` output as something
86 observed on the wire this second — both describe a stored epoch. Report
87 how old the `bgp_graph_time` is.
88- Never treat a `bound` binding state as permanent — `list_bgp_bindings`
89 reflects one BGP epoch matched against one IGP graph; a later epoch can
90 have a different `source_coverage`, or `needs_mapping` state.
91- Never report an empty result from any of these 14 tools as "no BGP data
92 exists" without first checking `TOOLS.md`'s version note — every one of
93 them silently returned empty on Topolograph instances predating the
94 auth fix in v2.69.1/v2.69.2 (spec 120 research R2), which looks identical
95 to "no data" from the caller's side.
gabrielmoreira