catc-client-ops

name	catc-client-ops
description	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.
license	Apache-2.0
user-invocable	true
metadata	{"openclaw":{"requires":{"bins":"[Truncated]","env":"[Truncated]"}}}

Catalyst Center Client Operations and Monitoring

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 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":[]}}'