Meraki API Patterns

Meraki MCP Tools & API Patterns

Overview

The Cisco Meraki MCP server provides AI tool integration with the Meraki cloud-managed networking platform via the Dashboard API v1. It exposes 27 tools spanning organizations, networks, devices, clients, wireless (MR), switching (MS), and the security appliance (MX), plus a meraki_raw_request passthrough that reaches any Dashboard API v1 endpoint. Meraki models everything as organizations -> networks -> devices, where a device is identified by its immutable serial number (e.g. Q2XX-XXXX-XXXX).

Connection & Authentication

Gateway Header Authentication

The MCP gateway authenticates to Meraki using headers you supply, and translates them to the upstream Meraki API internally:

The gateway maps X-Meraki-Api-Key to the upstream Meraki Authorization: Bearer <key> header for you. You never send the Authorization header directly -- the MCP server handles that translation.

Generate credentials at: Meraki Dashboard > Organization > Settings > Dashboard API access (then generate the key under My Profile).

Environment Variables:

export MERAKI_API_KEY="your-api-key"
export MERAKI_ORG_ID="123456"   # optional default org

IMPORTANT: Never hardcode credentials. Always use environment variables. The key inherits the permissions of the Dashboard account that generated it -- prefer a least-privilege service account.

Regional Clouds

Meraki operates isolated regional clouds. Override MERAKI_BASE_URL to target a non-global cloud:

Keys are not shared across clouds. Using the wrong base URL returns authentication errors or empty results.

Available MCP Tools

The server exposes exactly 27 tools, grouped by domain.

Navigation

Organizations

Networks

Devices

Clients

Wireless (MR)

Switching (MS)

Security Appliance (MX)

Long-Tail Passthrough

meraki_raw_request is the escape hatch for the hundreds of Dashboard API v1 endpoints the curated tools do not wrap -- live tools (ping, cable test, throughput), sensor readings (MT), camera endpoints (MV), licensing, alerts/uplink history, traffic analytics, and more. See "The Raw Request Escape Hatch" below.

Pagination

Meraki uses Link-header cursor pagination, not offset/page numbers.

• Pass perPage to control page size (endpoint-specific max, commonly 1000)
• The response Link header contains rel="next" / rel="prev" URLs carrying opaque startingAfter and endingBefore cursors
• To page forward, extract the startingAfter cursor from the next link and pass it on the following call
• Continue until no rel="next" link is present

Example workflow:

1. Call a list tool (or meraki_raw_request) with perPage=1000
2. Inspect the Link header for a rel="next" cursor
3. Re-call with startingAfter=<cursor> until the next link disappears
4. Never rely on page numbers -- cursors are opaque and must be passed through verbatim

Rate Limiting

Meraki enforces a ~10 requests/second per-organization limit (shared across all callers using that org).

• HTTP 429 responses include a Retry-After header (seconds) -- honor it exactly
• Use exponential backoff on repeated 429s
• Prefer organization-wide aggregate endpoints (e.g. org device statuses) over looping per-device
• Increase perPage to reduce the number of round-trips
• Serialize bulk operations; do not fan out concurrent writes against a single org

Read-Only Mode & Destructive Actions

The MCP server defaults to READ_ONLY_MODE=true.

• Read tools always work.
• Write tools (meraki_networks_update, meraki_wireless_ssids_update, meraki_switch_ports_update, meraki_clients_update_policy, meraki_appliance_firewall_l3_update) are exposed; whether they execute depends on server configuration.
• Destructive tools (meraki_networks_delete, meraki_devices_remove) always require an explicit confirm_destructive_action=true argument. Without it, the call is rejected.

Convention: Always read and present the current state (e.g. current firewall rules, current SSID config) before proposing a write, and require explicit user confirmation before setting confirm_destructive_action=true.

The Raw Request Escape Hatch

meraki_raw_request reaches any Dashboard API v1 endpoint the curated tools do not cover. Provide:

• method -- GET, POST, PUT, or DELETE
• path -- the API path relative to the v1 base (e.g. /networks/{networkId}/appliance/uplinks/statuses)
• body -- request payload for POST/PUT (optional)

Common uses:

Live tools are asynchronous: the initial POST returns a job ID and status URL; poll the corresponding GET .../liveTools/ping/{id} until status is complete.

Error Handling

Common Error Codes

Error Response Format

{
  "errors": [
    "Invalid API key"
  ]
}

Meraki returns errors as an errors array of human-readable strings.

Best Practices

• Resolve the hierarchy top-down: meraki_organizations_list -> meraki_networks_list -> meraki_devices_list
• Identify devices by serial, never by name -- names are mutable and non-unique
• Set a default MERAKI_ORG_ID when you manage a single org to skip the selection step
• Always page with cursors (startingAfter) via the Link header; never assume all results fit in one page
• Honor Retry-After on 429 and keep to the ~10 req/s per-org budget
• Read current state before any write; require explicit confirmation before destructive actions
• Reach for meraki_raw_request for live tools, sensors, cameras, licensing, and uplink history -- these are not curated tools
• Prefer org-wide aggregate endpoints over per-device loops to conserve the rate budget

Related Skills

• devices - Device inventory and lifecycle
• troubleshooting - Live-tools workflows via raw_request
• security-appliance - MX firewall and VPN