automateyournetwork/catc-client-ops

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