Data quality MCP and SQL reference

Use the PostHog MCP server to discover subjects, create and manage checks, start runs, read results, and change schedules. Use the data quality information-schema tables to list existing coverage and analyze recent outcomes with SQL.

Permissions and scopes

Every data quality operation requires query access. You also need access to the subject and every other subject that the check reads.

• Read operations require viewer access to the subject.
• Creating, updating, deleting, or running a check requires editor access to its subject.
• Updating a schedule requires editor access to the scheduled subject.
• A relationships check also requires access to its target.
• A custom_sql check requires access to every table or view selected by the query.
• Metric checks require Data Catalog access. Table, view, and PostHog-table checks require warehouse object access.

For a personal API key, include query:read and the matching subject scope. Use warehouse_table:read or warehouse_table:write for warehouse and PostHog tables, warehouse_view:read or warehouse_view:write for views, and data_catalog:read or data_catalog:write for metrics. The broader warehouse_objects:read and warehouse_objects:write scopes also grant access to warehouse subjects.

PostHog filters subject discovery, definitions, results, health, and notifications with the same access rules. A subject that you can't read doesn't appear as a partial or redacted row.

Unified MCP tools

The data quality MCP surface has eight enabled tools. These tools work across tables, views, metrics, and PostHog tables, so you don't need a subject-specific tool name.

Create and run a check

Start with subject discovery instead of guessing an ID:

1. Call data-quality-subjects.
2. Find the subject and copy its subject_type and id.
3. Call data-quality-check-types with the subject type.
4. Query system.information_schema.data_quality_checks to avoid creating overlapping coverage.
5. Call data-quality-check-create.

For example, create an error-severity check on orders.customer_id:

{
  "subject_type": "table",
  "subject_uuid": "<orders subject id>",
  "check_type": "not_null",
  "column_name": "customer_id",
  "config": {},
  "name": "orders_customer_id_not_null",
  "description": "Every order must belong to a customer",
  "severity": "error"
}

The create tool is idempotent for the same subject and assertion. A near-duplicate with different configuration creates separate coverage, so inspect existing checks first.

Call data-quality-check-run with the returned check id, and save the suite id that it returns. The tool returns this suite run before the individual check finishes. Poll the historical results from data-quality-check-results with the check ID until a result whose suite_run equals the saved suite ID is passed, failed, errored, or skipped. Inspect that matched result.

Update or delete a check

Call data-quality-check-update with the check ID to change its name, description, type, column, configuration, severity, enabled state, or tags. The subject is fixed. An update keeps the check ID, latest status, and run history.

Call data-quality-check-delete to soft-delete a check. The definition no longer runs, but its retained past rows remain in system.information_schema.data_quality_check_runs. A deleted check releases its name and assertion so you can create them again as a new check.

Manage schedules

Call data-quality-check-schedule with subject_type, subject_uuid, and at least one setting to change:

{
  "subject_type": "posthog_table",
  "subject_uuid": "<events subject id>",
  "interval": "6hour",
  "enabled": true
}

The schedule tool supports metric and posthog_table subjects. It rejects table and view because their checks run after data changes. The supported intervals are 1hour, 6hour, 12hour, 24hour, and 7day.

A subject gets its schedule when you add its first check. The unified MCP tool can update a schedule, but it can't read the current settings. To inspect them, open Data Warehouse > Data quality and expand the metric or PostHog table. A metric's Tests tab shows the same controls. If an update returns an uncertain result, reload that page before you make another MCP call.

Query check definitions

Use system.information_schema.data_quality_checks to find active definitions:

SELECT
    id,
    name,
    subject_type,
    subject_name,
    column_name,
    check_type,
    config,
    severity,
    enabled,
    last_status,
    last_run_at
FROM system.information_schema.data_quality_checks
ORDER BY subject_name, name

Filter by subject_name, subject_type, check_type, or enabled when you need a smaller result. subject_status = 'orphaned' means the subject no longer resolves.

Query recent runs

Use system.information_schema.data_quality_check_runs to inspect recent failed and errored runs:

SELECT
    check_id,
    suite_run_id,
    subject_name,
    check_type,
    status,
    failed_row_count,
    observed_value,
    error,
    duration_ms,
    created_at
FROM system.information_schema.data_quality_check_runs
WHERE status IN ('failed', 'errored')
ORDER BY created_at DESC
LIMIT 100

This table is bounded to the newest 500 readable runs. A soft-deleted check's retained run rows keep their check_id. The value becomes null only if the check definition is later hard-deleted. Use data-quality-check-results when you need the compiled query from a specific check run.

Query subject health

Use system.information_schema.data_quality_health to find subjects that need attention:

SELECT
    subject_type,
    subject_name,
    health,
    checks_total,
    checks_failing,
    checks_erroring,
    last_run_at
FROM system.information_schema.data_quality_health
WHERE health IN ('failing', 'erroring', 'warn')
ORDER BY last_run_at DESC

The health table includes enabled checks only. Subjects with no checks don't appear. An empty information-schema result can also mean you don't have permission to read the matching subjects.