Model Context Protocol

runZero supports the Model Context Protocol (MCP) at the /mcp endpoint, over streaming HTTP. Through it, AI clients query runZero’s security inventory directly and answer questions about your network assets and vulnerabilities.

The console.runzero.com URLs in this article are examples. Use the endpoint for your runZero deployment instead.

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.

Models that were not built for tool use or function calling struggle with MCP. They may lack the mechanisms or training to interpret tool schemas, decide when to call a tool, or parse its output reliably. Forcing MCP onto such a model is likely to produce frequent errors and hallucinations, or leave it unable to use the tools effectively.

How much data runZero holds affects the quality of responses. Larger models tend to handle larger data sets better, and prompting for exactly what you need, with filtering criteria, helps the model return the information you asked for.

MCP terms

AI client

The interface and communication layer between a human user (or another system) and an AI model. Its job is to carry input to the model and present the model’s output, and it is often reactive to user input.

AI agent

A more capable version of that client, one that orchestrates multiple steps and makes its own decisions. Asked to “Summarize this document,” an agent might first decide it needs a “file reading tool” to reach the document, have the LLM summarize what it retrieved, and then proactively suggest sharing the summary by email without being told to.

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

You can connect in two ways, depending on what your AI client supports.

OAuth. The client sends you to the runZero console, you approve what it may reach, and runZero issues it a scoped credential of its own. Nothing is copied and pasted, the credential is limited to what you approved, and it expires. This is the better option, and most current MCP clients support it. See Connecting through OAuth.

A credential you supply. You create an API key or an API client yourself and configure it in the client, usually as a request header. Use this when the client cannot do OAuth, or when the connection belongs to a system rather than a person. See Presenting a credential directly.

What a credential can reach

The credential decides the access. The MCP server offers a client only the tools its credential permits, so a read-only credential is not offered start_scan and cannot call it.

Credential	Prefix	Organizations	Access
OAuth connection	-	What you approved	What you approved, never more than your own access
API client	-	The client’s grant	The client’s grant
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

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

Connecting through OAuth

Point the client at https://console.runzero.com/mcp and let it authenticate. The client discovers runZero as its authorization server, registers itself, and opens a browser. You sign in to the console if you are not already signed in, and land on an approval page.

The approval page tells you which application is asking and where the authorization code will be sent, then asks two questions:

What this application may reach. Read one organization, read and write one organization, or, for superusers, read and write every organization in the account. Only organizations where you can manage API clients are offered.
A name for the credential, so you can tell your connections apart later.

Superusers get a third choice, Credential binding, between a user-bound credential tied to their own access and an account-bound credential that is not. Everyone else gets a user-bound credential.

Approving creates an API client on your account and hands the application an authorization code, which it exchanges for an access token. Denying creates nothing.

What the connection can and cannot do

The credential an approval creates is deliberately narrow:

It cannot manage API credentials, scan credentials, console users, or account settings, whatever you approved and whatever your own access is.
It is limited to what you approved, and, when user-bound, to your current access. If your access narrows, the connection narrows with it. If your account is locked or removed, the connection stops working.
It expires 90 days after approval. That deadline cannot be moved, so renewing the connection means reconnecting the application, which creates a new credential. See Expiration.
Its access token is valid only for the MCP endpoint; the REST API refuses it.

Approvals are capped at 40 active connections per account.

Managing and revoking connections

A connection created this way is an API client like any other. Find it under My API clients, or, for account-bound ones, on the Account API clients page, and delete it to revoke access immediately. Approvals and the credentials they create are recorded in the audit log.

To approve a connection you need permission to manage API credentials (tokens:manage) in at least one organization, which the Administrator role grants. Without it, the approval page tells you so and nothing is created. Approving for the whole account requires a superuser with a Platform license.

Presenting a credential directly

For clients that cannot do OAuth, or for unattended connections, create a credential yourself and configure it in the client. runZero accepts three shapes.

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. For a client that can only be configured with OAuth client 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 you created. 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. The client’s grant decides what the connection can reach, so this is the way to give an unattended integration a narrow, long-lived MCP connection.

OAuth endpoints

When a request carries no usable credential, runZero answers with a 401 whose WWW-Authenticate header points at the protected resource metadata, so a client can find its way without being configured 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 endpoints, grant, and PKCE support (RFC 8414).
`/oauth/register`	Dynamic client registration (RFC 7591), for clients with no client ID metadata document.
`/oauth/authorize`	The approval page.
`/api/v1.0/account/api/token`	The token endpoint.

runZero offers the authorization code grant with PKCE using S256, and supports both dynamic client registration and client ID metadata documents, so a client can register itself without anyone provisioning it first. Registration issues a public client ID and stores nothing. Redirect URIs must use HTTPS, or HTTP on a loopback address. Authorization codes are single use, and no refresh token is issued.

The client credentials exchange described in Presenting a credential directly remains available for API keys and API clients, but it is not advertised as an OAuth grant.

Organization scope

Every inventory tool takes an optional organization_ids argument. Omit it and the call covers the whole scope of the credential: the organizations named in an API client’s grant or approved for an OAuth connection, every organization in the account for an account API token, 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 substituting a different one.

Clients

MCP standardizes how AI agents talk to external tools, but how each client implements that connection can vary significantly with its 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.

If the client supports OAuth, that is all the configuration it needs. It will send you to the console to approve the connection, as described in Connecting through OAuth. If it does not, configure a credential yourself as described in Presenting a credential directly.

Claude

Claude Desktop and Claude.ai connect to remote servers as a custom connector rather than through claude_desktop_config.json.

On a Free, Pro, or Max plan, go to Settings > Connectors and choose Add custom connector. On a Team or Enterprise plan, an owner adds it from Organization settings > Connectors with Add > Custom, and members then connect to it individually.

Enter https://console.runzero.com/mcp as the server URL and leave Authentication on Always required, which Claude pre-fills because the MCP endpoint answers an anonymous request with a 401. Leave the OAuth client setting on its default; Claude registers itself with runZero automatically.

The first time you use the connector, Claude opens the console in a browser. Sign in if you are not already signed in, choose what the connector may reach, name it, and approve. Claude finishes the connection and the connector is ready to use.

Because each member of a Team or Enterprise organization connects the shared connector separately, each one approves their own credential and reaches only what their own runZero access permits. Nobody sees another member’s inventory through the connector, and revoking one person’s runZero access revokes their connection without affecting anyone else’s.

The credential expires after 90 days. Reconnecting the connector in Claude creates a new one.

Anthropic documents the dialog field by field in Third party connectors with remote MCP.

Claude Code

Add the server with the http transport and no credential:

claude mcp add --transport http runzero https://console.runzero.com/mcp

The first call to the server opens a browser for approval. Confirm the result with claude mcp list, which reports whether each configured server connected, and use /mcp inside Claude Code to check or re-run authentication.

To use a credential you created yourself instead, pass it as a header, which turns off the OAuth flow for that server:

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

Gemini CLI

The Gemini CLI also supports MCP, configured mainly through its settings.json file.

The user-scoped settings.json should be at ~/.gemini/settings.json (where ~ is your home directory).

You can find or create the system-wide settings.json at:

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

For more on configuration, see the project’s configuration documentation.

Replace the token value below with one created as described in Presenting a credential directly, and leave the other settings Gemini wrote (theme, selected authentication type, and so on) as they are.

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

Other options

You should be able to adapt the configurations above to other tools. Most of these clients support OAuth, in which case no credential needs to be configured at all. Follow each client’s documentation for remote or streaming-HTTP servers rather than its stdio instructions:

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 gets 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 runs an asset query and returns the exact match count plus an optional risk-ranked sample. Views: count, compact, lifecycle, security, detail.
query_asset_counts counts up to eight labeled asset queries in one batch, with no rows. Use it for comparisons and category breakdowns instead of repeated query_assets calls.
query_services searches the service inventory, including TLS fields.
query_certificates searches the certificate inventory, sorted by earliest validity end.
query_tasks searches scan and integration tasks. The series view returns up to 2,000 runs with timings and result counts for charting.
query_inventory searches 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 returns selected host-level attributes for 1-20 assets in one batch.
list_organizations lists the organizations the credential can reach, with summary asset counts.

Writing queries

get_field_definitions returns 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 returns the query-writing documentation for one entity: operators, worked examples, and that entity’s fields. It covers every entity area get_field_definitions lists.
translate_query turns 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 searches the vulnerability match rules runZero ships, by CVE, vendor, or product. This is platform detection coverage, not your findings.
search_scan_checks searches the active scan checks runZero ships, by CVE, check ID, product, or tag.
list_rapid_response returns 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 returns device type, OS, and attack surface distributions, security-control signal counts, and the total asset count.
get_subnets returns per-subnet rollups (/24 for IPv4, /48 for IPv6) with dominant device types and gateway hints.
list_assets_in_subnet lists the assets whose primary address falls within a CIDR.
search_assets returns compact asset rows matching a case-insensitive substring across address, name, OS, type, and service products.
get_outliers returns assets with notable outlier scores, annotated with the dimensions that make them unusual.
get_exposed_assets returns externally exposed and high-risk internal assets, tagged so the two are not conflated.
get_datastores returns assets exposing databases, file shares, NFS, SMB, and object storage.
get_security_controls returns the histogram of detected EDR, MDM, encryption, firewall, and TLS posture signals.
get_critical_systems returns high-impact assets tagged by role: network core, OT control, identity, hypervisor, datastore, management plane.
get_rogue_assets returns hosts seen by discovery with no identity, EDR, MDM, or configuration-management source.
get_eol_assets returns expired and near-end-of-life assets with their OS version, EOL date, site, and risk.
get_eol_crosstab returns the end-of-life heat-map cells by site or business unit and OS family.
get_explorers lists connected Explorers with their reachable networks, site, and system details.
get_recent_tasks lists recent scans and integration syncs, useful for judging data freshness.
get_latest_metrics returns the latest precomputed metric snapshots.
get_goals lists the security goals the organization is tracking.

Scanning

start_scan starts 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 can neither see nor call it.

Retired tools

The tool set converged on the AI thread tools, so several 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 runs locally and lets you add the API key directly in the UI. Once connected, you can copy the server entry to connect other agents, although it may not be the exact configuration the client needs.

$ npx @modelcontextprotocol/inspector@latest

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

Updated September 17, 2026

← Using the CLI

Glossary →

Model Context Protocol

MCP terms

AI client

AI agent

Model Context Protocol

Authentication

What a credential can reach

Connecting through OAuth

What the connection can and cannot do

Managing and revoking connections

Who can approve a connection

Presenting a credential directly

OAuth endpoints

Organization scope

Clients

Connecting to remote MCP servers

Claude

Claude Code

Gemini CLI

Other options

Available tools

Inventory search

Writing queries

Detection coverage and rapid response

Organization analytics

Scanning

Retired tools

Prompts and resources

Exploring MCP tools, resources, and prompts