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.

Connection & Authentication

Bearer Token Auth

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

Header	Description
Authorization	Bearer <your-account-api-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:

Token Type	Scope	Use Case
Account API Token	Full account access	General API usage
Organization API Token	Single org access	Scoped integrations
Export API Token	Read-only exports	Bulk data retrieval

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

Available MCP Tools

Assets

Tool	Description
runzero_assets_list	List assets with filters (site, OS, type)
runzero_assets_get	Get detailed asset information
runzero_assets_search	Search assets by query string
runzero_assets_export	Export assets in bulk via Export API

Tasks (Scans)

Tool	Description
runzero_tasks_list	List scan tasks
runzero_tasks_get	Get scan task details and results
runzero_tasks_create	Create and start a new scan task
runzero_tasks_stop	Stop a running scan task

Sites

Tool	Description
runzero_sites_list	List organization sites
runzero_sites_get	Get site details
runzero_sites_create	Create a new site
runzero_sites_update	Update site configuration

Services

Tool	Description
runzero_services_list	List discovered services
runzero_services_get	Get service details
runzero_services_export	Export services in bulk

Wireless

Tool	Description
runzero_wireless_list	List discovered wireless networks
runzero_wireless_get	Get wireless network details

Explorers

Tool	Description
runzero_explorers_list	List deployed explorers (scan agents)
runzero_explorers_get	Get explorer details and status

Export API

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

Export Endpoints

Resource	Description
Assets	Export all assets with full attribute data
Services	Export all discovered services
Wireless	Export all wireless networks
Software	Export discovered software inventory

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

Code	Meaning	Resolution
401	Unauthorized	Check API token
403	Forbidden	Token lacks required scope
404	Not Found	Resource doesn't exist or wrong ID
429	Rate Limited	Wait and retry after delay
500	Server Error	Retry; contact support if persistent

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

Field	Description	Example
os	Operating system	os:Windows
type	Asset type	type:server
hostname	Hostname	hostname:DC01
address	IP address	address:192.168.1.0/24
protocol	Service protocol	protocol:ssh
port	Service port	port:443
alive	Asset is alive	alive:true
last_seen	Last seen time	last_seen:<7d
site_id	Site UUID	site_id:<uuid>

Operators

Operator	Description
:	Equals / contains
:<	Less than
:>	Greater than
AND	Logical AND
OR	Logical OR
NOT	Logical NOT

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
• Handle rate limits gracefully with exponential backoff
• 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