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.

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.

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.

Connection Configuration

  1. Create an Account API Key
    1. The Client API Token can be used by the MCP client to connect with the HTTP header Authorization: Bearer CT***
  2. Add the key to the MCP agent
    1. Each client is different and we provide guidance for some common methods of adding MCP support to clients.

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

To help navigate differences in MCP client capabilites, we will use mcp-remote to connect to remote MCP servers. It allows us to provide an Authorization header, and navigate clients’ rapidly maturing remote connection capabilities.

This will necessitate that you have Node installed on your system. Examples for how to do so can be found on the official Node download page.

Claude Desktop

Claude Desktop is configured through the claude_desktop_config.json file that can be found here:

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

This is also described on the official MCP site.

Replace the client token value below with the token created in Connection Configuration above.

{
  "mcpServers": {
    "runZero MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://console.runzero.com/mcp",
        "--header",
        "Authorization:${RZ_TOKEN}'"
      ],
      "env": {
        "RZ_TOKEN": "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 the token created in Connection Configuration above, and leave other configuration details (theme, selected authentication type, etc) unchanged from values provided by Gemini.

{
  "mcpServers": {
    "runZero MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://console.runzero.com/mcp",
        "--header",
        "Authorization:${RZ_TOKEN}"
      ],
      "env": {
        "RZ_TOKEN": "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. Note that if you adapt the above configuration via mcp-remote, you will want to follow stdio-based documentation.

Using the MCP server

Once connected, try submitting something like the following to get an idea of how to best utilize the MCP server’s capabilities.

Please tell me about the tools exposed by the runZero MCP integration.

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.
Updated
Previous: Using the CLI Next: Glossary