Vicarius vRx MCP Server

A Model Context Protocol server that exposes the Vicarius vRx External Data API (REST) to AI assistants. It provides 88 tools across 37 API domains — Vulnerabilities/CVEs, Endpoints (Assets), Patches & Updates, Publishers & Products, Tasks & Events, Automations & Scripts, Users, and more — plus a generic vrx_request escape hatch for anything not covered by a dedicated tool. The tool set is generated directly from the vRx OpenAPI specification, so it stays faithful to the real API surface, and the generated output is deterministic and committed.

Tools

88 tools across 37 API controllers (59 read + 29 mutating), plus the vrx_request escape hatch — 89 total in full mode, 60 in read-only mode (mutating tools are not registered when read-only). The table below groups the controllers into functional domains.

See docs/ENDPOINTS.md for the full tool ↔ method ↔ path mapping (all 88 tools with their mutating flag).

Highlights:

• Search tools (endpoint_search, vulnerability_search, organization_endpoint_group_search, …) accept an RSQL q filter plus from/size paging — see Querying.

• Filter / count tools (*_filter, *_count) cover event streams (incident events, task events) and counts for dashboards.

• Aggregation tools (aggregation_group, aggregation_search_group) power grouped/rollup queries (e.g. count of active CVEs grouped by vulnerability).

• vrx_request escape hatch issues an arbitrary request against the API for any endpoint without a dedicated tool. In read-only mode it rejects every non-GET method.

• Read-only safety is enforced at two layers — mutating tools are never registered in read-only mode, and vrx_request independently refuses mutations.

Related MCP server: Integrations MCP

Quick start

Install

# with uv (recommended)
uv tool install vrx-mcp

# or with pip
pip install vrx-mcp

This installs the vrx-mcp console script. For development from source:

git clone https://github.com/Space-C0wboy/vicarius-vrx-mcp-server
cd vicarius-vrx-mcp-server
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
# .venv/bin/python -m pip install -e ".[dev]"      # macOS/Linux

Getting an API key

1. In the vRx portal, go to Settings, select the api tag, then Create Integration.

2. Copy the generated API key — this is your VRX_API_KEY.

3. Your base URL is https://<your-dashboard>.vicarius.cloud/vicarius-external-data-api.

Requests authenticate with the vicarius-token header (the API key value); this server sets it for you on every request.

Configuration

Copy .env.example to .env and set:

Run

• stdio (default, for Claude Desktop/Code): vrx-mcp

• HTTP: vrx-mcp --transport http --port 8765

Querying

vRx search endpoints use RSQL in the q query parameter:

Pagination: every query takes from (offset) and size. size ≤ 500 per request and from ≤ 10,000. To page beyond offset 10,000, use seek paging: keep from=0, add a sort (e.g. -endpointId), and add a q comparison on the last value seen (e.g. q=endpointId<525236), repeating until the result is empty.

Response envelope: responses wrap results in a standard shape — serverResponseResult.serverResponseResultCode ("SUCCESS"), serverResponseCount (total matching records), and serverResponseObject (the array of records).

Rate limits: the API allows 60 queries / 60 seconds per organization scope and returns HTTP 429 with an X-Rate-Limit-Retry-After-Seconds header when exceeded. The client automatically retries 429s (and transient 5xx/network errors) with backoff, honoring that header.

Read-only mode

Set VRX_READ_ONLY=true to run the server safely against production. In this mode:

• No mutating tools are registered — only the 59 read tools (+ vrx_request) are exposed.

• vrx_request rejects any non-GET method, so it can only run read operations.

Read-only mode is strongly recommended for analyst-assistant, reporting, and dashboard use cases where the model should never change tenant state. The shipped .env.example defaults to read-only.

Editor integration

Claude Code

claude mcp add vrx \
  --env VRX_API_KEY=your-key-here \
  --env VRX_BASE_URL=https://your-dashboard.vicarius.cloud/vicarius-external-data-api \
  --env VRX_READ_ONLY=true \
  -- vrx-mcp

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vrx": {
      "command": "vrx-mcp",
      "env": {
        "VRX_API_KEY": "your-key-here",
        "VRX_BASE_URL": "https://your-dashboard.vicarius.cloud/vicarius-external-data-api",
        "VRX_READ_ONLY": "true"
      }
    }
  }
}

Restart Claude Desktop, then confirm vrx appears in the tools menu.

Example prompts

• "List the first 100 assets in vRx." → endpoint_search (from=0, size=100).

• "Find the asset named HOST01." → endpoint_search (q=endpointName=='HOST01').

• "Show me all Critical CVEs." → vulnerability_search (q=vulnerabilitySensitivityLevel.sensitivityLevelName=='Critical').

• "Which assets are affected by CVE-2024-3094?" → vulnerability_search to resolve the CVE, then endpoint_search with a searchQuerys join body on OrganizationEndpointVulnerabilities.

• "List endpoints with critical missing patches." → organization_endpoint_external_reference_external_references_search (q=...patchSensitivityLevel.sensitivityLevelName=='Critical').

• "Get attack vectors and links for a vulnerability." → vulnerability_attack_vectors_search_by_fields / vulnerability_links_search_by_fields (q=vulnerabilityId==<id>).

• "Show the recent event log." → incident_event_filter (sort + analyticsEventCreatedAtNano range).

• "Count active CVEs grouped by vulnerability." → aggregation_search_group.

• "Call an endpoint I don't have a tool for." → vrx_request (method, path, query, body).

How tools are generated

The tool modules are generated from the vRx OpenAPI specification:

python scripts/generate_from_openapi.py "Reference Material/api-docs.json"

This regenerates the modules under src/vrx_mcp/tools/_generated/ and the catalog at docs/ENDPOINTS.md. The generated files are not hand-edited — to change a tool, edit the generator (its OVERRIDES / MUTATING_OVERRIDES maps) and regenerate. Generation is deterministic, so re-running it produces a byte-identical, reviewable diff.

The OpenAPI spec and other vRx reference material live in the Reference Material/ directory, which is gitignored (vendor/customer-proprietary material, not redistributed).

Key generator behavior:

• Operations are grouped by OpenAPI controller tag into one module per domain.

• Redundant GET/POST search twins are collapsed to a single tool (the POST/body form).

• Each operation is classified mutating (PUT/DELETE, or a non-search POST) or read (GET, or a search-style POST); mutating tools are hidden in read-only mode.

Development

.venv/Scripts/python -m pytest        # full suite (httpx fully mocked; no live calls)
.venv/Scripts/python -m ruff check .  # lint
.venv/Scripts/python scripts/generate_from_openapi.py "Reference Material/api-docs.json"  # regenerate

CI runs ruff + pytest on Python 3.10 / 3.11 / 3.12 (see .github/workflows/ci.yml).

Maintainers: see CONTRIBUTING.md for the release process.

License

MIT

Support

This is an unofficial, internal project. For vRx platform or API questions, contact Vicarius directly. For issues with this MCP server, open an issue on the GitHub repository.