runZero API Patterns

RunZero MCP Tools & API Patterns

Overview

The RunZero MCP server provides AI tool integration with the RunZero asset discovery and network security platform. It exposes tools covering asset inventory, network scanning, site management, service discovery, wireless detection, and vulnerability reporting. The API uses Bearer token authentication with an Account API Token.

Anti-triggers

• Running an export. This skill explains the Export API's mechanics; the tools that actually pull bulk data are runzero_assets_export in runzero-assets and runzero_services_export in runzero-services.
• Deciding what to scan. Query-language syntax lives here, but scan scope and rate belong to runzero-tasks and runzero-sites.

Connection & Authentication

Bearer Token Auth

RunZero authenticates using an Account API Token passed as a Bearer token:

Generate credentials at: RunZero Console > Account > API Keys

Environment Variables:

export RUNZERO_API_TOKEN="your-account-api-token"

IMPORTANT: Never hardcode credentials. Always use environment variables.

Token Types

RunZero supports multiple token scopes:

For MCP usage, use an Account API Token for broadest access.

Available MCP Tools

Assets

Tasks (Scans)

Sites

Services

Wireless

Explorers

Export API

RunZero provides a dedicated Export API for bulk data retrieval. This is the preferred method for large datasets.

Export Endpoints

Export Filters

Exports support RunZero's query language for filtering:

os:Windows AND site_id:<uuid>
protocol:rdp AND alive:true
type:server AND last_seen:<30d

Pagination

The RunZero API uses offset-based pagination:

• Results are returned in pages with configurable size
• Use offset and count parameters to navigate
• Default page size is typically 100 records
• Continue fetching until fewer results than count are returned

Example workflow:

1. Call runzero_assets_list with count=100 and offset=0
2. If 100 results returned, call again with offset=100
3. Repeat until fewer than count results are returned

Rate Limiting

RunZero enforces API rate limits per token:

• Monitor X-RateLimit-Remaining response headers
• HTTP 429 responses indicate rate limit exceeded
• Wait before retrying -- use exponential backoff
• Use the Export API for bulk operations to reduce call count

Error Handling

Common Error Codes

Error Response Format

{
  "error": "Unauthorized",
  "message": "Invalid or expired API token"
}

RunZero Query Language

RunZero uses a powerful query language for filtering assets and services:

Syntax

field:value AND field:value OR field:value

Common Fields

Operators

Best Practices

• Use the Export API for large dataset retrieval instead of paginating list endpoints
• Apply query filters to scope results to relevant assets
• Use site-based filtering to generate per-client reports
• Cache site and explorer metadata to reduce API calls
• Use Organization API Tokens for scoped integrations

Related Skills

• assets - Asset inventory and search
• tasks - Scan task management
• sites - Site management
• services - Service discovery
• wireless - Wireless network detection