Setting Up Monitors as Code

This guide walks you through your first Monitors as Code (MaC) deployment — from CLI setup to a running monitor.

Prerequisites

Install the Monte Carlo CLI and configure your credentials:

pip install montecarlodata
montecarlo configure

📘

If pip install fails with an "externally managed environment" error (common on modern macOS), use pipx install montecarlodata or create a virtual environment first:

Bash

python3 -m venv mac-env && source mac-env/bin/activate
pip install montecarlodata

montecarlo configure prompts for your API key ID and token. Generate these in Settings > API Keys in the Monte Carlo UI.

Verify the connection:

montecarlo validate

You should see: Hi, <name>! All is well.

📘

Alternative: environment variables

Instead of running montecarlo configure, you can set MCD_DEFAULT_API_ID and MCD_DEFAULT_API_TOKEN environment variables. See the CI/CD guide for details.

Project setup

Create a project directory and add a montecarlo.yml file at the root:

mkdir mac-project && cd mac-project

# montecarlo.yml
version: 1

If you have multiple warehouses connected to Monte Carlo, specify which one to use. Find your warehouse name in Settings > Integrations > Warehouses and Lakes in the Monte Carlo UI.

# montecarlo.yml
version: 1
default_resource: <warehouse name or UUID>

Monitor definitions go in separate YAML files — not in montecarlo.yml itself. A typical layout:

mac-project/
  montecarlo.yml
  monitors/
    sales_checks.yml
    pipeline_health.yml

The CLI scans all .yml and .yaml files recursively by default. You can control this with include_file_patterns and exclude_file_patterns in montecarlo.yml.

Create your first monitor

Start with a Custom SQL monitor — it works with any warehouse and any query.

montecarlo:
  custom_sql:
    - name: row_count_check
      description: Alert if the orders table has zero rows
      sql: SELECT COUNT(*) FROM db.schema.orders
      alert_conditions:
        - operator: EQ
          threshold_value: 0
      schedule:
        type: fixed
        interval_minutes: 720

For a metric monitor example, see Metric Monitor Quick Start.

Replace db.schema.orders with a real table in your warehouse. In table fields (YAML), use database:schema.table — a colon separates the database from the schema (e.g., my_database:my_schema.orders). In sql fields, use your warehouse's native SQL syntax (typically database.schema.table).

Preview and deploy

Preview what will happen without making changes:

montecarlo monitors apply --namespace my-first-mac --dry-run

The dry run shows which monitors would be created, updated, or deleted. Review the output, then apply for real:

montecarlo monitors apply --namespace my-first-mac

Your monitor is now live. Find it in the Monte Carlo UI under Monitors, filtered by the my-first-mac namespace.

To remove all monitors in a namespace:

montecarlo monitors delete --namespace my-first-mac

Authoring with AI

AI coding assistants generate, validate, and manage MaC YAML for you. Monte Carlo's Agent Toolkit integrates with Claude Code, Cursor, and other MCP-compatible tools.

Available tools

• Monte Carlo MCP server — Use the create_or_update_*_monitor tools to interactively author monitors, where * is the monitor type. The MCP server validates your definitions against the API and, with dry_run=True, returns the rendered YAML without saving the monitor. Available tools:
  • create_or_update_table_monitor
  • create_or_update_metric_monitor
  • create_or_update_comparison_monitor (metric comparison)
  • create_or_update_sql_monitor (custom SQL / validation)
  • create_or_update_validation_monitor
• Monitoring advisor — The /monitoring-advisor skill analyzes your tables and recommends what to monitor based on usage patterns, lineage, and existing coverage gaps.
• Manage MaC — The /manage-mac skill creates, edits, and validates MaC YAML files directly in your project. It handles schema correctness and namespace management.

Install the toolkit: github.com/monte-carlo-data/mcd-agent-toolkit

Next steps

• Monitors as Code overview — all 8 monitor types with full YAML examples (includes schedule and alert condition details per type)
• CI/CD integration — GitHub Actions, GitLab CI, and CircleCI patterns
• Generating monitors from dbt tests — convert existing dbt tests to MaC