catc-client-ops

SKILL.md

Catalyst Center Client Operations and Monitoring

Comprehensive client visibility through Cisco Catalyst Center (formerly DNA Center). This skill covers client enumeration, filtering, detailed client inspection by MAC address, client count analytics, time-based trend analysis, and wireless client troubleshooting.

Catalyst Center MCP Server

All Catalyst Center tool calls use this invocation pattern:

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 -u $CATC_MCP_SCRIPT

Variable shorthand used throughout this document:

CATC_CMD="CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 -u $CATC_MCP_SCRIPT"

How to Call Tools

Use the $MCP_CALL protocol handler to invoke MCP tools:

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" TOOL_NAME 'ARGS_JSON'

When to Use

  • Monitoring wired and wireless client populations
  • 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
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF"}'

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.

3. get_clients_count -- Count Clients Matching Filters

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).

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless"}'

Client Operations Workflows

Workflow 1: Find All Wireless Clients on a Specific SSID

Step 1: Get the time 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 '{"time_window":"last 2 hours"}'

Extract startTime and endTime from the response.

Step 2: Count clients on the SSID first

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"]}'

If count > 100, narrow with additional filters (site, band, OS) before listing.

Step 3: List the clients

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"]}'

If count exceeded 100, narrow by site:

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","ssid":["Corporate-WiFi"],"site_hierarchy":["Global/USA/NYC/Floor2"]}'

Workflow 2: Investigate a Client by MAC Address

Full client investigation for help desk escalation or security incident.

Step 1: Get the time 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 '{"time_window":"last 24 hours"}'

Step 2: Fetch detailed client info

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000}'

Step 3: With additional wireless views

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000,"view":["Wireless","WirelessHealth"]}'

Analyze the results:

  • Connection state: Is the client currently connected? What is the connection time?
  • Network attachment: Which switch/AP is it connected to? Which interface/SSID?
  • IP assignment: Does it have a valid IP? DHCP or static?
  • Health score: Client health score (0-10). Below 7 indicates issues.
  • For wireless clients: RSSI, SNR, channel, band, data rate, AP name
  • OS information: OS type and version for security posture assessment

Workflow 3: Count Clients Per Site

Build a site-by-site client distribution report.

Step 1: Get the time 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 '{"time_window":"last 1 hours"}'

Step 2: Get the site hierarchy

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" fetch_sites '{}'

Step 3: Count clients at each site

# Site 1
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"]}'

# Site 2
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/CHI"]}'

Step 4: Break down by wired vs wireless per site

# Wired clients at NYC
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"],"client_type":"wired"}'

# Wireless clients at NYC
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"site_hierarchy":["Global/USA/NYC"],"client_type":"wireless"}'

Build the report:

Client Distribution Report
===========================
Catalyst Center: $CCC_HOST
Time Window: Last 1 hour (2025-01-15 14:00 - 15:00 UTC)

+----------------------------+-------+--------+----------+-------+
| Site                       | Total | Wired  | Wireless | %WiFi |
+----------------------------+-------+--------+----------+-------+
| Global/USA/NYC             | 1,245 |    320 |      925 | 74.3% |
|   NYC/Floor1               |   412 |    110 |      302 | 73.3% |
|   NYC/Floor2               |   498 |    130 |      368 | 73.9% |
|   NYC/Floor3               |   335 |     80 |      255 | 76.1% |
| Global/USA/CHI             |   876 |    250 |      626 | 71.5% |
| Global/USA/LAX             |   534 |    180 |      354 | 66.3% |
+----------------------------+-------+--------+----------+-------+
| TOTAL                      | 2,655 |    750 |    1,905 | 71.8% |
+----------------------------+-------+--------+----------+-------+

Workflow 4: Time-Based Client Trend Analysis

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.

Build the trend report:

Client Count Trend (Wireless)
==============================
Site: Global/USA/NYC
Date: 2025-01-15

Hour (UTC)    | Count  | Delta  | Bar
--------------+--------+--------+---------------------------
06:00 - 07:00 |    245 |    --  | ============
07:00 - 08:00 |    512 |  +267  | =========================
08:00 - 09:00 |    891 |  +379  | ============================================
09:00 - 10:00 |  1,102 |  +211  | ======================================================
10:00 - 11:00 |  1,189 |   +87  | ===========================================================
11:00 - 12:00 |  1,156 |   -33  | =========================================================
12:00 - 13:00 |    987 |  -169  | =================================================
13:00 - 14:00 |  1,134 |  +147  | ========================================================

Peak: 1,189 clients at 10:00-11:00 UTC
Trough: 245 clients at 06:00-07:00 UTC

Workflow 5: OS Distribution Analysis

Understand the client OS mix for security posture and compatibility planning.

Step 1: Get time 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 '{"time_window":"last 1 hours"}'

Step 2: Count clients per OS type

# Windows clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Windows"]}'

# macOS clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["macOS"]}'

# iOS clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["iOS"]}'

# Android clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Android"]}'

# Linux clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"os_type":["Linux"]}'

Workflow 6: Wireless Band Distribution

Analyze the 2.4 GHz vs 5 GHz vs 6 GHz client distribution for RF planning.

# 2.4 GHz clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["2.4GHz"]}'

# 5 GHz clients
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["5GHz"]}'

# 6 GHz clients (Wi-Fi 6E)
CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_count '{"start_time":1705312800000,"end_time":1705399200000,"client_type":"wireless","band":["6GHz"]}'

RF planning flags:

  • More than 40% of clients on 2.4 GHz -> WARNING: Poor band steering, co-channel interference risk
  • 5 GHz utilization > 80% of wireless clients -> HEALTHY: Good band steering configuration
  • 6 GHz adoption < 5% when Wi-Fi 6E APs are deployed -> INFO: Check client capability and SSID configuration

Workflow 7: Find a Client by IP Address

Locate a client on the network when you only know the IP (common for security investigations).

Step 1: Get the time 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 '{"time_window":"last 4 hours"}'

Step 2: Search by IP

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"ipv4_address":["10.1.50.42"]}'

Step 3: Get full details using the MAC from the response

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_client_details_by_mac '{"client_mac_address":"AA:BB:CC:DD:EE:FF","start_time":1705312800000,"end_time":1705399200000}'

Workflow 8: Clients Connected to a Specific Network Device

Identify all clients connected through a particular switch or AP.

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"connected_network_device_name":["ACC-SW-01"]}'

Workflow 9: Clients on a Specific WLC

CCC_HOST=$CCC_HOST CCC_USER=$CCC_USER CCC_PWD=$CCC_PWD python3 $MCP_CALL "python3 -u $CATC_MCP_SCRIPT" get_clients_list '{"start_time":1705312800000,"end_time":1705399200000,"wlc_name":["WLC-NYC-01"]}'

Wireless Client Troubleshooting Reference

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":[]}}'
Weekly Installs
2
GitHub Stars
282
First Seen
10 days ago
Installed on
mcpjam2
claude-code2
replit2
junie2
windsurf2
zencoder2