Model Context Protocol

Community Platform

runZero supports the Model Context Protocol (MCP) at the /mcp endpoint and utilizes streaming-HTTP for communication. This integration allows clients to directly access runZero’s comprehensive security inventory data, enabling advanced, AI-driven queries and insights into network assets and vulnerabilities.

The MCP server offers the same tools as the console’s AI threads, so a question you can ask in the console can also be asked from an external client. See Available tools.

Some models are not designed with “tool use” or “function calling” in mind and will struggle. They might lack the internal mechanisms or sufficient training to reliably interpret tool schemas, decide when to call a tool, or correctly parse its output. Trying to force MCP onto such models would likely lead to frequent errors, hallucinations, or simply an inability to use the tools effectively.

The amount of data that is available in runZero will impact the quality of responses. Larger models tend to be able to process larger data sets better but prompting for exactly what is needed along with filtering criteria will help get the information being asked for.

MCP Terms

AI Client

The interface and communication layer between a human user (or another system) and an AI model. Its primary job is to enable interaction and present AI outputs. It’s often reactive to user input. It facilitates the use of AI.

AI Agent

An advanced version of that chat application that, upon receiving “Summarize this document,” might first decide it needs to use a “file reading tool” to access the document. The LLM can then summarize the retrieved document contents, and then proactively suggest sharing the summary via email without being explicitly told to. The agent orchestrated multiple steps and made decisions.

Model Context Protocol

From the MCP specification:

Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

Authentication

The MCP endpoint accepts API keys and API client credentials. The credential defines the access control.

Access control

Credential	Prefix	Organizations	Access
Account API token	CT	Every organization in the account	Read-write
Organization API token	OT	The token’s organization	Read-write
Export token	ET	The token’s organization	Read-only
API client	—	Every organization in the account	Read-write

Download tokens (DT) are refused, because they do not map onto an inventory scope.

A read-only credential does not offered write tools. As an example, calling MCP with an export token can read inventory but cannot start a scan.

Presenting the credential

Three credential shapes are accepted, so a client can connect whether it supports bearer tokens, OAuth, or both.

API key as a bearer token. The simplest option, for any client that can send a custom header:

Authorization: Bearer CT********

API key as an OAuth secret. Many MCP clients can only be configured with OAuth credentials. Use the client ID token and put the API key in the client secret. Send it as HTTP basic auth against the MCP endpoint, or exchange it at the token endpoint first, which validates the key and returns it as the access token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=token" \
  --data-urlencode "client_secret=CT********" \
  https://console.runzero.com/api/v1.0/account/api/token

Registered API client. Use the client ID and secret of an API client created on the API clients page. Send them as HTTP basic auth against the MCP endpoint, or exchange them at the token endpoint for an access token the way the REST API does. API clients are account-wide.

OAuth discovery

A request with no usable credential is answered with a 401 whose WWW-Authenticate header points at the protected resource metadata, so an OAuth-aware client can find its way without being told the token endpoint by hand.

Endpoint	Purpose
/.well-known/oauth-protected-resource	Names the console as the authorization server for /mcp (RFC 9728). Also served at /.well-known/oauth-protected-resource/mcp.
/.well-known/oauth-authorization-server	Advertises the token endpoint and supported grant (RFC 8414).
/api/v1.0/account/api/token	The token endpoint.

Only the client credentials grant is offered, with client_secret_basic and client_secret_post authentication. An MCP credential authenticates an account rather than an interactive user, so there is no authorization endpoint and no dynamic client registration; clients that require an authorization-code flow are not supported.

Organization scope

Every inventory tool takes an optional organization_ids argument. Omit it and the call covers the whole scope of the credential: every organization in the account for an account key or API client, and the single organization encoded into an organization key or export token.

An organization-scoped credential is narrowed to its own organization whether or not organization_ids was passed. Naming an organization outside the credential’s scope returns an error rather than quietly substituting a different one.

Clients

While the core concept of MCP is standardized communication between AI agents and external tools, how different clients implement this integration can vary significantly based on their design and intended use.

Connecting to remote MCP servers

Point the client at https://console.runzero.com/mcp and select Streamable HTTP as the transport. Depending on what the client supports, authenticate with either an Authorization: Bearer header or OAuth client credentials, as described in Authentication.

A client needs to be able to do one of those two things. An MCP credential authenticates an account rather than an interactive user, so a client that can only sign in through an interactive authorization-code login cannot connect.

Claude Desktop

Claude Desktop connects to remote servers as a custom connector rather than through claude_desktop_config.json. In Settings → Connectors, choose Add custom connector, enter https://console.runzero.com/mcp, and complete the authentication prompt with your API key or API client credentials. Anthropic documents the flow in Getting started with custom connectors.

Claude Code

Add the server with the http transport, replacing the token with one created as described in Authentication:

claude mcp add --transport http runzero https://console.runzero.com/mcp --header "Authorization: Bearer CT********"

Gemini CLI

The Gemini CLI also has MCP support, primarily configured through the settings.json file.

User-scoped settings.json files should be found at ~/.gemini/settings.json (where ~ is your home directory).

The system-wide settings.json file can be found or created at:

• Linux: /etc/gemini-cli/settings.json
• macOS: /Library/Application\ Support/GeminiCli/settings.json
• Windows: C:\ProgramData\gemini-cli\settings.json

For more configuration information, please consult the project’s configuration documentation.

Replace the client token value below with a token created as described in Authentication, and leave other configuration details (theme, selected authentication type, etc) unchanged from values provided by Gemini.

{
  "mcpServers": {
    "runzero": {
      "httpUrl": "https://console.runzero.com/mcp",
      "headers": {
        "Authorization": "Bearer CT********"
      }
    }
  }
}

Other Options

The configurations above should be able to be adapted to other tools. Here are some potential options, including links to their respective documentation. Follow each client’s documentation for remote or streaming-HTTP servers rather than its stdio instructions.

• VSCode
• OpenAI Codex
• Cursor
• Windsurf
• Zed Editor

Available tools

MCP and AI threads run the same tools against the same inventory. Everything below is shared with AI threads except start_scan, which only MCP exposes. MCP offers the whole set at once; inside the console, each turn is given only the tools its task needs.

Every tool takes an optional organization_ids argument; see Organization scope.

Inventory search

Live queries against the inventory, written in runZero search syntax.

• query_assets – Run an asset query and return the exact match count plus an optional risk-ranked sample. Views: count, compact, lifecycle, security, detail.
• query_asset_counts – Count up to eight labeled asset queries in one batch, with no rows. Use this for comparisons and category breakdowns instead of repeated query_assets calls.
• query_services – Search the service inventory, including TLS fields.
• query_certificates – Search the certificate inventory, sorted by earliest validity end.
• query_tasks – Search scan and integration tasks. The series view returns up to 2,000 runs with timings and result counts for charting.
• query_inventory – Search any other inventory entity: software, software-group, vulnerability (with CVE, CVSS, and remediation text), vulnerability-group, wireless, finding, event, user, group, task, issue, goal, credential, query, and site.
• get_attributes – Return selected host-level attributes for 1-20 assets in one batch.
• list_organizations – List the organizations the credential can reach, with summary asset counts.

Writing queries

• get_field_definitions – The searchable fields for an entity or integration source, each with a description and example values. Call it with no argument for the index of areas and the integration sources present in the inventory.
• get_query_syntax – The query-writing documentation for one entity: operators, worked examples, and that entity’s fields. Every entity area get_field_definitions lists is supported.
• translate_query – Turn a plain-language phrase into runZero syntax. entity: "asset" with question: "find all cisco devices with ssh exposed" returns (os:cisco or hw:cisco or newest_mac_vendor:cisco) and protocol:ssh. The query is compiled but not executed, so it stays fast on large inventories; pass the result to query_assets or query_inventory to run it.

translate_query calls the account’s configured model, so it needs AI to be enabled and is subject to the same entitlement and budget as the console. When AI is unavailable the tool is not offered.

Detection coverage and rapid response

• search_vuln_coverage – Search the vulnerability match rules runZero ships, by CVE, vendor, or product. This is platform detection coverage, not your findings.
• search_scan_checks – Search the active scan checks runZero ships, by CVE, check ID, product, or tag.
• list_rapid_response – The account’s Rapid Response feed, each entry with the inventory query that finds affected assets.

Organization analytics

These read an organization-wide snapshot rather than running a query.

• get_overview – Device type, OS, and attack surface distributions, security-control signal counts, and the total asset count.
• get_subnets – Per-subnet rollups (/24 for IPv4, /48 for IPv6) with dominant device types and gateway hints.
• list_assets_in_subnet – The assets whose primary address falls within a CIDR.
• search_assets – Compact asset rows matching a case-insensitive substring across address, name, OS, type, and service products.
• get_outliers – Assets with notable outlier scores, annotated with the dimensions that make them unusual.
• get_exposed_assets – Externally exposed and high-risk internal assets, tagged so the two are not conflated.
• get_datastores – Assets exposing databases, file shares, NFS, SMB, and object storage.
• get_security_controls – The histogram of detected EDR, MDM, encryption, firewall, and TLS posture signals.
• get_critical_systems – High-impact assets tagged by role: network core, OT control, identity, hypervisor, datastore, management plane.
• get_rogue_assets – Hosts seen by discovery with no identity, EDR, MDM, or configuration-management source.
• get_eol_assets – Expired and near-end-of-life assets with their OS version, EOL date, site, and risk.
• get_eol_crosstab – The end-of-life heat-map cells by site or business unit and OS family.
• get_explorers – Connected Explorers with their reachable networks, site, and system details.
• get_recent_tasks – Recent scans and integration syncs, useful for judging data freshness.
• get_latest_metrics – The latest precomputed metric snapshots.
• get_goals – The security goals the organization is tracking.

Scanning

• start_scan – Start a scan in an organization, optionally against a specific site or Explorer.

This is the only tool that changes state and the only one MCP does not share with AI threads. Read-only credentials neither see it nor can call it.

Retired tools

The tool set converged on the AI thread tools, so a number of narrower tools were removed. Their replacements:

Retired tool	Use instead
query_software	query_inventory with entity software or software-group
query_vulnerabilities	query_inventory with entity vulnerability or vulnerability-group
query_findings, critical_findings, external_assets_critical_findings	query_inventory with entity finding
query_wireless	query_inventory with entity wireless
query_users	query_inventory with entity user
query_directory_group	query_inventory with entity group
list_sites	query_inventory with entity site
asset_remediation	query_inventory with entity vulnerability, which returns remediation text

For bulk, paginated exports of full records, use the export API rather than MCP.

Prompts and resources

Alongside the tools, the server offers:

• The critical_findings prompt, which takes an organization name or UUID and asks for that organization’s critical findings.
• The docs://querysyntax resource, which returns the search query syntax reference as Markdown.

Exploring MCP tools, resources, and prompts

MCP Inspector can be run locally and allows for the API key to be added directly in the UI. Once connected, the server entry can be copied and used for connection to other agents, although it may not be the exact configuration the client needs.

$ npx @modelcontextprotocol/inspector@latest

1. Enter Authorization as the API client key.
2. Connect to the server to view the tools and resources available.