Catalyst Center client operations and monitoring - list/filter wired and wireless clients, detailed client lookup by MAC, client count analytics, time-based analysis, SSID and band filtering, wireless troubleshooting. Use when looking up a client by MAC or IP, counting clients per site or SSID, analyzing wireless band distribution, or investigating Wi-Fi signal issues.
Catalyst Center client operations and monitoring - list/filter wired and wireless clients, detailed client lookup by MAC, client count analytics, time-based analysis, SSID and band filtering, wireless troubleshooting. Use when looking up a client by MAC or IP, counting clients per site or SSID, analyzing wireless band distribution, or investigating Wi-Fi signal issues.
Investigating specific client connectivity issues by MAC address
Capacity planning: how many clients per site, SSID, or band
Wireless troubleshooting: signal quality, RSSI, band steering analysis
Time-based analysis: client count trends over hours/days
Security investigations: locate a client by IP or MAC across the network
Help desk escalations: look up a user's device and connection details
SSID utilization and OS distribution analytics
Critical: Time Range Handling
The Catalyst Center client APIs require startTime and endTime in epoch milliseconds. The API enforces a 30-day maximum lookback for startTime.
ALWAYS call get_api_compatible_time_range FIRST to convert human-readable time ranges into valid epoch millisecond pairs before calling any client tool.
get_api_compatible_time_range -- Convert Time Ranges
Parameters:
time_window (string, optional): Human-readable relative time. Examples: "last 2 hours", "last 7 days", "today", "yesterday", "last 30 days". Takes precedence over ISO params if provided.
start_datetime_iso (string, optional): Specific start in ISO 8601 format (e.g., "2025-01-15T10:00:00Z")
end_datetime_iso (string, optional): Specific end in ISO 8601 format. Defaults to now if omitted.
Returns: JSON with startTime and endTime (epoch ms), adjusted_for_30_day_limit flag, and ISO timestamps for verification.
# Relative time window
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL"python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 2 hours"}'# Specific date range
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL"python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"start_datetime_iso":"2025-01-15T08:00:00Z","end_datetime_iso":"2025-01-15T17:00:00Z"}'# Today only
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL"python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"today"}'
IMPORTANT: If the response shows adjusted_for_30_day_limit: true, the requested start time exceeded the API's 30-day limit and was automatically clamped. Inform the user that the effective time range is shorter than requested.
Available Client Tools
1. get_clients_list -- List Connected Clients
Retrieves a list of clients from the /dna/data/api/v1/clients endpoint. Hard limit of 100 clients per call. If more than 100 clients match the filters, the tool returns the total count and a message requesting more specific filters instead of partial data.
Parameters:
Parameter
Type
Description
start_time
int
Epoch ms start time (use get_api_compatible_time_range)
end_time
int
Epoch ms end time
limit
int
Max clients to return (default 100, capped at 100)
offset
int
Starting record for pagination (default 1)
sort_by
str
Attribute to sort by (e.g., clientConnectionTime)
order
str
asc or desc (default asc)
client_type
str
"wired" or "wireless"
os_type
List[str]
OS filter: ["Windows"], ["macOS"], ["Android"], etc.
os_version
List[str]
OS version filter
site_hierarchy
List[str]
Full site path: ["Global/USA/NYC/Floor2"]
site_hierarchy_id
List[str]
Site hierarchy UUID(s)
site_id
List[str]
Site UUID(s)
ipv4_address
List[str]
Client IPv4 address(es)
ipv6_address
List[str]
Client IPv6 address(es)
mac_address
List[str]
Client MAC address(es)
wlc_name
List[str]
WLC name(s)
connected_network_device_name
List[str]
Network device name(s) clients are connected to
ssid
List[str]
SSID name(s)
band
List[str]
Wireless band(s): ["2.4GHz"], ["5GHz"], ["6GHz"]
view
List[str]
Additional data views: ["Wireless"], ["WirelessHealth"]
attribute
List[str]
Specific attributes to include
List type parameters (os_type, site_hierarchy, ssid, band, etc.) must be passed as JSON arrays of strings: ["value1","value2"].
2. get_client_details_by_mac -- Detailed Client Info by MAC
Fetches comprehensive details for a single client identified by MAC address from the /dna/data/api/v1/clients/{mac} endpoint.
Parameters:
client_mac_address (string, required): The MAC address of the client
start_time (int, optional): Epoch ms start time
end_time (int, optional): Epoch ms end time
view (List[str], optional): Additional data views
attribute (List[str], optional): Specific attributes
Response includes: Client MAC, IP address, hostname, OS type/version, connected device name, connected interface, VLAN, SSID (if wireless), band, channel, RSSI, SNR, data rate, connection time, health score, and more.
Automatic retries: If the API returns error code 14006 (data not ready for the requested endTime), the tool automatically retries with the API-suggested adjusted endTime.
Returns the total count of clients matching the specified filters from the /dna/data/api/v1/clients/count endpoint. Use this for analytics and capacity planning without retrieving full client records.
Parameters: Same filter parameters as get_clients_list (except limit, offset, sort_by, order, view, attribute).
Analyze how client counts change over time for capacity planning or anomaly detection.
Step 1: Define time windows (e.g., hourly snapshots over the last 8 hours)
# 8 hours ago to 7 hours ago
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL"python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"time_window":"last 8 hours"}'# Or use specific ISO ranges for precise hourly windows
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL"python3 -u $CATC_MCP_SCRIPT" get_api_compatible_time_range '{"start_datetime_iso":"2025-01-15T06:00:00Z","end_datetime_iso":"2025-01-15T07:00:00Z"}'
Step 2: Count clients for each time window
Run get_clients_count for each hourly window with the appropriate start_time and end_time values.
When investigating wireless client issues, use get_client_details_by_mac with the Wireless and WirelessHealth views and examine these key metrics:
RSSI (Received Signal Strength Indicator)
RSSI (dBm)
Quality
Action
-30 to -50
Excellent
No action needed
-50 to -60
Good
Acceptable for all applications
-60 to -67
Fair
VoIP may experience quality issues
-67 to -70
Weak
Consider AP placement or power adjustment
-70 to -80
Very Weak
Roaming and throughput issues likely
Below -80
Unusable
Client will disconnect or fail to associate
SNR (Signal-to-Noise Ratio)
SNR (dB)
Quality
Action
> 40
Excellent
No action needed
25-40
Good
Acceptable
15-25
Fair
May impact higher data rates
10-15
Poor
Significant throughput degradation
< 10
Unusable
Noise floor investigation required
Common Wireless Client Issues
Symptom
Likely Cause
Investigation
Low RSSI
Client too far from AP, physical obstructions
Check AP location, consider adding AP
Low SNR with OK RSSI
High noise floor
Check for interferers (microwave, Bluetooth, rogue APs)
Frequent disconnects
Sticky client, aggressive roaming
Check roaming threshold, 802.11r/k/v config
Slow throughput
Band steering failure, co-channel interference
Check band distribution, channel plan
Authentication failures
802.1X/RADIUS issue
Check ISE logs, certificate validity
DHCP failure
Scope exhaustion, VLAN mismatch
Check DHCP scope, verify VLAN assignment
Client Operations Report Format
Client Operations Report
=========================
Catalyst Center: $CCC_HOST
Time Window: 2025-01-15 14:00 - 15:00 UTC
Client Overview
---------------
Total Connected: 2,655
Wired: 750 (28.2%)
Wireless: 1,905 (71.8%)
Wireless Band Distribution
---------------------------
2.4 GHz: 285 (15.0%) -- HEALTHY (below 30% threshold)
5 GHz: 1,502 (78.8%) -- HEALTHY
6 GHz: 118 (6.2%) -- HEALTHY (Wi-Fi 6E adoption growing)
Top SSIDs
----------
Corporate-WiFi: 1,245 clients (65.4%)
Guest-WiFi: 412 clients (21.6%)
IoT-Devices: 248 clients (13.0%)
OS Distribution
----------------
Windows: 1,102 (41.5%)
macOS: 534 (20.1%)
iOS: 445 (16.8%)
Android: 312 (11.8%)
Linux: 98 (3.7%)
Other: 164 (6.2%)
Site Distribution
------------------
Global/USA/NYC: 1,245 (46.9%)
Global/USA/CHI: 876 (33.0%)
Global/USA/LAX: 534 (20.1%)
GAIT Audit Trail
After completing any client operations session, record the findings in GAIT:
python3 $MCP_CALL"python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"input":{"role":"assistant","content":"Catalyst Center client operations on $CCC_HOST: 2,655 total clients (750 wired, 1,905 wireless). Band distribution healthy: 15% on 2.4GHz, 79% on 5GHz, 6% on 6GHz. Top SSID: Corporate-WiFi (1,245 clients). OS mix: Windows 42%, macOS 20%, iOS 17%. No anomalies detected in the last 1-hour window.","artifacts":[]}}'
