/troubleshooting

name: "Meraki Troubleshooting"
description: >
  Read-only Cisco Meraki diagnostics through the hosted Meraki MCP: site and
  device outages from availability history and WAN uplink loss/latency,
  switch port status and error counters, LLDP/CDP topology, wireless
  connection failures and packet loss, client lookup by MAC, and "what
  changed?" from the change log and event log. Live tests are handed to a
  human in the Dashboard.
when_to_use: >-
  When diagnosing a Meraki problem -- a site or device is down, a WAN link is lossy, a switch port
  keeps dropping, Wi-Fi users cannot connect, a client cannot be found, or something broke after a
  change. Use when: meraki troubleshoot, site down, device offline, wan down, packet loss,
  latency, port not working, link flapping, crc errors, wifi not connecting, slow wifi, find
  client by mac, what changed, meraki event log, meraki ping, or cable test.

Meraki Troubleshooting

Overview

Troubleshooting through the hosted Meraki MCP is evidence-gathering: availability history, uplink loss and latency, port counters, wireless failure logs, client records, the change log and the event log. All of it is read with `execute_api`, using capability IDs found with `semantic_search`. Tool schemas and pagination are in `meraki-api-patterns`.

The hosted server cannot run live tests. Ping, traceroute, cable test, throughput test, blink LEDs, cycle port and packet capture are jobs created by write operations, which the server does not offer, and it cannot reboot anything. When the evidence points to a live test or a reboot, tell the human exactly which test to run, on which device, and where to find it in the Dashboard (see "Handing off live tests" below).

`semantic_search` may return capabilities named `getDeviceLiveTools...`. They only read back a job someone already created through the API, and need that job's ID. Do not use them to try to run a test.

Anti-triggers

• **"Is the customer's website up?"** -- Meraki sees the network from inside the customer site. External uptime checking is `betterstack-monitors`.
• **A workstation or server problem that is not a network problem** -- use `atera-devices` or `ncentral-devices`.
• **Deciding whether a firewall rule, NAT rule or VPN policy is blocking traffic** -- use `meraki-security-appliance`.
• **Inventory, EOX or firmware questions** -- use `meraki-devices`.

Triage Order

Work from the WAN inward: is the appliance online and its uplinks healthy, then the switch and port, then the AP and RF, then the client. A fault upstream makes everything downstream look broken, so do not diagnose an AP while its MX is offline.

Workflow: Site Down or Device Offline

1. **Who is down.** `getOrganizationDevicesAvailabilities` with `networkIds` for the site. Everything offline points at the site's MX, WAN or power; a single device points at that device, its cable or its switch port. 2. **Since when, and is it flapping.** `getOrganizationDevicesAvailabilitiesChangeHistory` with the `serials` and a `timespan` (max 31 days). Repeated online/offline transitions suggest a flapping WAN, power or PoE budget problem rather than a dead device. 3. **WAN status.** `getOrganizationApplianceUplinkStatuses` (MX and Z) or `getOrganizationUplinksStatuses` (also covers MG cellular gateways) with `networkIds`. Each uplink reports `active`, `ready`, `failed` or `not connected`. A site running on `cellular` while WAN1 is `failed` has failed over. 4. **Loss and latency now.** `getOrganizationDevicesUplinksLossAndLatency` returns the last few minutes (the newest point is about 2 minutes old) for every MX uplink and the destination IP it probes. 5. **Loss and latency over time.** `getDeviceLossAndLatencyHistory` needs both `serial` and `ip` -- the probe destination, taken from step 4 (often `8.8.8.8`). Add `uplink` (`wan1`, `wan2`, `cellular`), a `timespan` up to 31 days and a `resolution` (60, 600, 3600 or 86400 seconds). 6. **Active alerts.** `getOrganizationAssuranceAlerts` with `networkId` shows what the Dashboard itself has raised.

execute_api { "capability_id": "getDeviceLossAndLatencyHistory", "parameters": { "serial": "Q2XX-XXXX-XXXX", "ip": "8.8.8.8", "uplink": "wan1", "timespan": 86400, "resolution": 600 } }

**Reading it.** A `failed` uplink or sustained loss on one WAN is a carrier problem: give the human the circuit, the time window and the loss figures to quote to the ISP. Loss that appears only at busy hours suggests the circuit is saturated. If the MX is online with clean uplinks but its downstream devices are offline, move to the switch.

Workflow: Switch Port Problems

1. **Find the switch.** `getOrganizationDevices` with `productTypes: ["switch"]` and `name`, or `meraki-devices` to resolve a serial. 2. **Port state.** `getDeviceSwitchPortsStatuses` with `serial` and a `timespan` (default 1 day, max 31 days) returns per-port status, speed, duplex, errors, warnings and the CDP/LLDP neighbour. 3. **Error counters.** `getDeviceSwitchPortsStatusesPackets` with `serial` returns per-port packet counters, including CRC/alignment errors, collisions and topology changes. Its `timespan` snaps to 5 minutes, 15 minutes, 1 hour or 1 day. 4. **Across many switches.** `getOrganizationSwitchPortsStatusesBySwitch` with `networkIds`. Its `perPage` maxes out at 20 switches. 5. **What is plugged in where.** `getOrganizationSwitchPortsTopologyDiscoveryByDevice` lists the most recent LLDP/CDP neighbour per port (also `perPage` max 20). Use it to confirm an uplink lands where the diagram says, or to find which port an AP or phone is on.

execute_api { "capability_id": "getDeviceSwitchPortsStatusesPackets", "parameters": { "serial": "Q2XX-XXXX-XXXX", "timespan": 3600 } }

**Reading it.** CRC errors climbing on one port point at the physical layer: cable, patch lead, SFP or the far-end NIC. A gigabit device linking at 100 Mbps or half duplex points the same way. Frequent topology changes suggest a loop or a