ThousandEyes Path Analysis & Troubleshooting
MCP Servers
- Community:
src/server.py (stdio, Python 3.12+) — te_get_path_vis for path visualization
- Official:
https://api.thousandeyes.com/mcp (remote HTTP) — full path vis, BGP, instant tests, anomalies, endpoint agents
Key Capabilities
Path Visualization
| Source |
Tool |
What It Does |
| Community |
te_get_path_vis |
Hop-by-hop path from a specific agent to the test target |
| Official |
Get Path Visualization |
Network paths with routing details |
| Official |
Get Full Path Visualization |
Comprehensive path data aggregated across all agents |
Path visualization shows every network hop between agent and target:
- IP address and DNS name of each hop
- Latency per hop (pinpoints where delay is introduced)
- Packet loss per hop (identifies lossy links)
- MPLS labels (reveals traffic engineering paths)
- Network owner (ISP/carrier identification per hop)
BGP Route Analysis
| Tool |
What It Does |
| Get BGP Test Results |
BGP reachability — which BGP monitors see the prefix, which don't |
| Get BGP Route Details |
AS path, origin AS, prefix length, route stability |
BGP analysis provides external routing visibility:
- Prefix reachability from ThousandEyes' global BGP monitor fleet
- AS path — is traffic routing through expected carriers?
- Route changes — detect BGP hijacks, leaks, or suboptimal routing
- Origin validation — verify the prefix originates from the correct AS
Outage Investigation
| Tool |
What It Does |
| Search Outages |
Find network and application outages with time/scope filters |
| List Events |
Network/application problems with affected targets |
| Get Event Details |
Deep dive: impacted tests, affected agents, timeline |
Active Troubleshooting
| Tool |
What It Does |
| Instant Tests |
Run tests on demand from selected agents — don't wait for scheduled cycles |
| Get Anomalies |
Detect metric deviations from baseline over time |
| Views Explanations |
AI-powered explanation of test results and visualizations |
Endpoint Diagnostics
| Tool |
What It Does |
| List Endpoint Agents and Tests |
Endpoint agents on user workstations with test associations |
| Get Endpoint Agent Metrics |
WiFi signal, VPN tunnel latency, DNS response, HTTP performance |
Workflow: "Why Is Site X Slow?"
The classic ThousandEyes troubleshooting workflow:
- Identify test:
te_list_tests (community) filtered by target site
- Check results:
te_get_test_results (community) — is latency elevated? Packet loss?
- Path visualization:
te_get_path_vis (community) — hop-by-hop analysis
- Full path: Get Full Path Visualization (official) — all agents, compare paths
- Pinpoint hop: identify the hop where latency spikes or loss appears
- BGP check: Get BGP Route Details (official) — is routing suboptimal?
- Anomalies: Get Anomalies (official) — when did the degradation start?
- Report: "Latency increase traced to hop 7 (ISP-X backbone router 203.0.113.45). AS path changed at 14:32 UTC — traffic now routing through AS 64512 instead of direct peering. BGP route via AS 65001 withdrawn."
Workflow: Internet Outage Triage
When ThousandEyes detects a broad outage:
- Search outages: Search Outages (official) — scope: ISP, CDN, SaaS provider?
- Events: List Events (official) — which tests are affected?
- Event details: Get Event Details (official) — impacted targets, severity, timeline
- Path vis:
te_get_path_vis (community) for affected tests — where does the path break?
- BGP: Get BGP Test Results (official) — prefix still reachable? Route withdrawn?
- Instant test: Instant Tests (official) — verify from multiple cloud agents
- Report: outage scope, affected services, root cause, estimated provider recovery
Workflow: Endpoint VPN Troubleshooting
When users report VPN issues:
- List endpoint agents: List Endpoint Agents and Tests (official) — affected users
- Endpoint metrics: Get Endpoint Agent Metrics (official) — WiFi signal, DNS, VPN latency
- Path visualization: Get Path Visualization (official) — user to VPN gateway path
- Compare: run enterprise agent test to same VPN gateway — is it user-side?
- Anomalies: Get Anomalies (official) — when did metrics degrade?
- Report: "User WiFi signal -72 dBm (poor), DNS response 450ms (ISP DNS slow). VPN tunnel latency 180ms due to WiFi retransmissions. Recommend: switch to 5 GHz band, use corporate DNS."
Workflow: BGP Hijack / Leak Detection
When validating BGP route security:
- BGP tests:
te_list_tests (community) filtered by BGP test type
- BGP results: Get BGP Test Results (official) — reachability from global monitors
- Route details: Get BGP Route Details (official) — AS paths from all vantage points
- Anomalies: unexpected AS in path? Prefix originated from wrong AS?
- Path vis: Get Full Path Visualization (official) — confirm traffic follows expected path
- Cross-reference:
pyats-routing for internal BGP state confirmation
- Report: BGP security assessment with route origin validation
Integration with Other Skills
| Skill |
How They Work Together |
te-network-monitoring |
Monitoring provides context (tests, dashboards), path analysis provides deep investigation |
pyats-routing |
ThousandEyes external BGP + pyATS internal BGP = complete routing picture |
pyats-troubleshoot |
ThousandEyes internet path + pyATS device-level CLI diagnostics |
meraki-security-appliance |
ThousandEyes path through MX + Meraki VPN status for SD-WAN troubleshooting |
aws-network-ops |
ThousandEyes cloud agent + AWS VPC flow logs for hybrid path analysis |
fmc-firewall-ops |
ThousandEyes path vis shows traffic traversing FTD + FMC rule analysis |
servicenow-change-workflow |
Outage events trigger ServiceNow incidents with ThousandEyes evidence |
gait-session-tracking |
Record all path analysis and troubleshooting in GAIT |
Important Rules
- Instant Tests consume test units — use judiciously; each run counts against your ThousandEyes license
- Path visualization requires network layer tests — HTTP server tests won't show full path data
- BGP monitors are global — ThousandEyes has 300+ BGP vantage points; results reflect internet-wide routing
- Endpoint agents need permission — endpoint data is privacy-sensitive; respect data governance
- Time ranges matter — narrow queries to the incident window to reduce API load and improve relevance
- Record in GAIT — log all path analysis, outage investigations, and BGP findings
Environment Variables
TE_TOKEN — ThousandEyes API v7 OAuth bearer token (shared with te-network-monitoring)
1---2name: te-path-analysis3description: Cisco ThousandEyes — path visualization, BGP route analysis, outage investigation, instant tests, endpoint agent diagnostics. Use when tracing network paths hop-by-hop, investigating why a site is slow, analyzing BGP route changes, diagnosing an internet outage, or troubleshooting VPN from endpoint agents.4license: Apache-2.05---6
7# ThousandEyes Path Analysis & Troubleshooting
8
9## MCP Servers
10
11- **Community**: `src/server.py` (stdio, Python 3.12+) — `te_get_path_vis` for path visualization
12- **Official**: `https://api.thousandeyes.com/mcp` (remote HTTP) — full path vis, BGP, instant tests, anomalies, endpoint agents
13
14## Key Capabilities
15
16### Path Visualization
17
18| Source | Tool | What It Does |
19|--------|------|--------------|
20| Community | `te_get_path_vis` | Hop-by-hop path from a specific agent to the test target |
21| Official | Get Path Visualization | Network paths with routing details |
22| Official | Get Full Path Visualization | Comprehensive path data aggregated across all agents |
23
24Path visualization shows every network hop between agent and target:
25- **IP address** and **DNS name** of each hop
26- **Latency** per hop (pinpoints where delay is introduced)
27- **Packet loss** per hop (identifies lossy links)
28- **MPLS labels** (reveals traffic engineering paths)
29- **Network owner** (ISP/carrier identification per hop)
30
31### BGP Route Analysis
32
33| Tool | What It Does |
34|------|--------------|
35| Get BGP Test Results | BGP reachability — which BGP monitors see the prefix, which don't |
36| Get BGP Route Details | AS path, origin AS, prefix length, route stability |
37
38BGP analysis provides external routing visibility:
39- **Prefix reachability** from ThousandEyes' global BGP monitor fleet
40- **AS path** — is traffic routing through expected carriers?
41- **Route changes** — detect BGP hijacks, leaks, or suboptimal routing
42- **Origin validation** — verify the prefix originates from the correct AS
43
44### Outage Investigation
45
46| Tool | What It Does |
47|------|--------------|
48| Search Outages | Find network and application outages with time/scope filters |
49| List Events | Network/application problems with affected targets |
50| Get Event Details | Deep dive: impacted tests, affected agents, timeline |
51
52### Active Troubleshooting
53
54| Tool | What It Does |
55|------|--------------|
56| Instant Tests | Run tests on demand from selected agents — don't wait for scheduled cycles |
57| Get Anomalies | Detect metric deviations from baseline over time |
58| Views Explanations | AI-powered explanation of test results and visualizations |
59
60### Endpoint Diagnostics
61
62| Tool | What It Does |
63|------|--------------|
64| List Endpoint Agents and Tests | Endpoint agents on user workstations with test associations |
65| Get Endpoint Agent Metrics | WiFi signal, VPN tunnel latency, DNS response, HTTP performance |
66
67## Workflow: "Why Is Site X Slow?"
68
69The classic ThousandEyes troubleshooting workflow:
70
711. **Identify test**: `te_list_tests` (community) filtered by target site
722. **Check results**: `te_get_test_results` (community) — is latency elevated? Packet loss?
733. **Path visualization**: `te_get_path_vis` (community) — hop-by-hop analysis
744. **Full path**: Get Full Path Visualization (official) — all agents, compare paths
755. **Pinpoint hop**: identify the hop where latency spikes or loss appears
766. **BGP check**: Get BGP Route Details (official) — is routing suboptimal?
777. **Anomalies**: Get Anomalies (official) — when did the degradation start?
788. **Report**: "Latency increase traced to hop 7 (ISP-X backbone router 203.0.113.45). AS path changed at 14:32 UTC — traffic now routing through AS 64512 instead of direct peering. BGP route via AS 65001 withdrawn."
79
80## Workflow: Internet Outage Triage
81
82When ThousandEyes detects a broad outage:
83
841. **Search outages**: Search Outages (official) — scope: ISP, CDN, SaaS provider?
852. **Events**: List Events (official) — which tests are affected?
863. **Event details**: Get Event Details (official) — impacted targets, severity, timeline
874. **Path vis**: `te_get_path_vis` (community) for affected tests — where does the path break?
885. **BGP**: Get BGP Test Results (official) — prefix still reachable? Route withdrawn?
896. **Instant test**: Instant Tests (official) — verify from multiple cloud agents
907. **Report**: outage scope, affected services, root cause, estimated provider recovery
91
92## Workflow: Endpoint VPN Troubleshooting
93
94When users report VPN issues:
95
961. **List endpoint agents**: List Endpoint Agents and Tests (official) — affected users
972. **Endpoint metrics**: Get Endpoint Agent Metrics (official) — WiFi signal, DNS, VPN latency
983. **Path visualization**: Get Path Visualization (official) — user to VPN gateway path
994. **Compare**: run enterprise agent test to same VPN gateway — is it user-side?
1005. **Anomalies**: Get Anomalies (official) — when did metrics degrade?
1016. **Report**: "User WiFi signal -72 dBm (poor), DNS response 450ms (ISP DNS slow). VPN tunnel latency 180ms due to WiFi retransmissions. Recommend: switch to 5 GHz band, use corporate DNS."
102
103## Workflow: BGP Hijack / Leak Detection
104
105When validating BGP route security:
106
1071. **BGP tests**: `te_list_tests` (community) filtered by BGP test type
1082. **BGP results**: Get BGP Test Results (official) — reachability from global monitors
1093. **Route details**: Get BGP Route Details (official) — AS paths from all vantage points
1104. **Anomalies**: unexpected AS in path? Prefix originated from wrong AS?
1115. **Path vis**: Get Full Path Visualization (official) — confirm traffic follows expected path
1126. **Cross-reference**: `pyats-routing` for internal BGP state confirmation
1137. **Report**: BGP security assessment with route origin validation
114
115## Integration with Other Skills
116
117| Skill | How They Work Together |
118|-------|----------------------|
119| `te-network-monitoring` | Monitoring provides context (tests, dashboards), path analysis provides deep investigation |
120| `pyats-routing` | ThousandEyes external BGP + pyATS internal BGP = complete routing picture |
121| `pyats-troubleshoot` | ThousandEyes internet path + pyATS device-level CLI diagnostics |
122| `meraki-security-appliance` | ThousandEyes path through MX + Meraki VPN status for SD-WAN troubleshooting |
123| `aws-network-ops` | ThousandEyes cloud agent + AWS VPC flow logs for hybrid path analysis |
124| `fmc-firewall-ops` | ThousandEyes path vis shows traffic traversing FTD + FMC rule analysis |
125| `servicenow-change-workflow` | Outage events trigger ServiceNow incidents with ThousandEyes evidence |
126| `gait-session-tracking` | Record all path analysis and troubleshooting in GAIT |
127
128## Important Rules
129
130- **Instant Tests consume test units** — use judiciously; each run counts against your ThousandEyes license
131- **Path visualization requires network layer tests** — HTTP server tests won't show full path data
132- **BGP monitors are global** — ThousandEyes has 300+ BGP vantage points; results reflect internet-wide routing
133- **Endpoint agents need permission** — endpoint data is privacy-sensitive; respect data governance
134- **Time ranges matter** — narrow queries to the incident window to reduce API load and improve relevance
135- **Record in GAIT** — log all path analysis, outage investigations, and BGP findings
136
137## Environment Variables
138
139- `TE_TOKEN` — ThousandEyes API v7 OAuth bearer token (shared with te-network-monitoring)
gabrielmoreira