io.github.icedq-tools/mcp-server

---

How It Works?

The iceDQ MCP Server connects Claude Desktop, VS Code, Cursor, and Claude Code to your iceDQ Data Reliability Platform instance, letting you manage data quality using natural language. Ask your AI assistant to explore databases, files, or REST APIs; profile data; and create Validation, Duplicate, Checksum, Pushdown, and Reconciliation rules (including API Validation and API Recon) — then execute, monitor, and analyze results, all through conversation.

Rules created through MCP tools are published immediately and ready to execute. The server also bundles eight agent skills (skills/) that guide authoring, comparison, API testing, runs, and schedules. Parameter names and schemas are listed in TOOLS.md.

49 tools covering the full data quality lifecycle:

Capability	What you can do
Data Exploration	Browse workspaces, connections, databases, schemas, tables, columns, files, and REST APIs
Data Profiling	Fetch real sample data and analyze quality metrics (nulls, patterns, types)
AI Suggestions	Get intelligent check recommendations based on your data profile
Validation Rules	Row-level NotNull, Format, ValidValues, Length, Date, and Custom Groovy checks on DB, files, or APIs
Duplicate Detection	Identify duplicates on business keys, composite keys, or conditional criteria
Pushdown Rules	SQL-driven aggregate validation (GROUP BY, JOINs, referential integrity)
Checksum Rules	Cross-source comparison (row counts, sums) between two different connections
Reconciliation	Row-level matching across databases, files, and APIs, with AI-powered join-key mapping
Workflows	Chain multiple rules into sequential execution workflows
Schedules	Automate rule execution with one-time, daily, or weekly schedules
Custom Functions	Create and update Java/Groovy UDFs (Evaluator or Processor type)
Data Warehouse Queries	Run structured, schema-validated queries against iceDQ's execution history datasets
Execution & Monitoring	Run rules on demand, track status, and view exception reports
Organization	Manage folders, move rules in batch, create reusable parameters

---

System Requirements

Requirement	Details
Operating System	Windows 10+, macOS 10.15+, or Linux (see note below)
AI Client	One of: Claude Desktop, VS Code, or Cursor (latest version)
Node.js	20.0.0+ (required for npx-based setup; the Claude Desktop extension bundles its own runtime)
iceDQ	v7.5.0+ with a valid user account

Linux users: Install via the npx method (works in VS Code and Cursor). The packaged Claude Desktop extension (.mcpb) is currently macOS and Windows only because Claude Desktop itself does not ship a Linux build.

---

Quick Start

Step 1 — Get Your iceDQ Credentials

You need six values from your iceDQ instance before you can configure the MCP server:

• iceDQ Base URL
• Realm (default iam.icedq)
• Client ID and Client Secret (created in iceDQ → Administration → Security → Client Credentials)
• Your iceDQ username and password
• Organization ID (read from any rule's metadata)

For step-by-step instructions with screenshots, see the Credentials Guide.

Step 2 — Install via npm

The iceDQ MCP Server is published on npm as @icedq/mcp-server. Most AI clients can launch it automatically with npx — no manual download or build step required.

Add the following to your AI client's MCP configuration:

{
  "mcpServers": {
    "icedq": {
      "command": "npx",
      "args": ["-y", "@icedq/mcp-server"],
      "env": {
        "ICEDQ_BASE_URL": "https://app.icedq.net",
        "ICEDQ_REALM": "iam.icedq",
        "ICEDQ_CLIENT_ID": "<your-client-id>",
        "ICEDQ_CLIENT_SECRET": "<your-client-secret>",
        "AUTH_TYPE": "username_password",
        "ICEDQ_USERNAME": "<your-username>",
        "ICEDQ_PASSWORD": "<your-password>",
        "ICEDQ_ORG_ID": "<your-org-id>",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

Configuration Reference

Variable	Required	Description
ICEDQ_BASE_URL	Yes	Base URL of your iceDQ instance (e.g. https://app.icedq.net)
ICEDQ_REALM	Yes	Authentication realm (default iam.icedq)
ICEDQ_CLIENT_ID	Yes	OAuth client ID for API authentication
AUTH_TYPE	Yes	username_password, access_token, or device_flow
ICEDQ_ORG_ID	Yes	Your iceDQ organization ID
ICEDQ_CLIENT_SECRET	For username_password	OAuth client secret
ICEDQ_USERNAME	For username_password	Your iceDQ username
ICEDQ_PASSWORD	For username_password	Your iceDQ password
TOKENS_PATH	For access_token	Path to a token JSON file with accessToken and refreshToken
REMEMBER_ME	Optional, for device_flow	Defaults to remembering the cached session. Set to false to wipe stored tokens and force a fresh browser login
VERIFY_SSL	Optional	Defaults to true. Set to false only for self-signed certificates
REQUEST_TIMEOUT	Optional	API request timeout in seconds (default 30)
DEBUG	Optional	Set to true for verbose logging
LOG_LEVEL	Optional	error, warn, info, or debug (default info)
NODE_OPTIONS	Optional	Set to --use-system-ca so Node trusts your OS certificate store (needed if your iceDQ instance uses a corporate/self-signed CA)

Claude Desktop users can install the packaged extension instead of editing JSON — follow the setup guide below.

Alternative: Device Flow Authentication (no password required)

Instead of supplying a username and password, you can authenticate via Device Flow (RFC 8628) — the server opens a browser login page for you, and tokens are cached securely in your OS keychain (Windows Credential Manager, macOS Keychain, or Linux libsecret) so you only log in once. This is the recommended option for SSO/MFA-enabled accounts or shared machines where you don't want credentials stored in the MCP config.

{
  "mcpServers": {
    "icedq": {
      "command": "npx",
      "args": ["-y", "@icedq/mcp-server"],
      "env": {
        "ICEDQ_BASE_URL": "https://app.icedq.net",
        "ICEDQ_REALM": "iam.icedq",
        "ICEDQ_CLIENT_ID": "<your-client-id>",
        "AUTH_TYPE": "device_flow",
        "ICEDQ_ORG_ID": "<your-org-id>",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

On first run, the server prints a verification URL and code to the console and opens your browser automatically. Once you log in, tokens are cached (OS keychain, falling back to a token file) and silently refreshed on subsequent runs — no need to re-authenticate. Set REMEMBER_ME=false to skip the cache and force a fresh login every time. See the Device Flow internals guide for details.

Alternative: Access Token Authentication (pre-issued tokens)

If you already have an OAuth access/refresh token pair (e.g. issued by your own automation or a prior login), point the server at a token JSON file instead of supplying credentials directly:

{
  "mcpServers": {
    "icedq": {
      "command": "npx",
      "args": ["-y", "@icedq/mcp-server"],
      "env": {
        "ICEDQ_BASE_URL": "https://app.icedq.net",
        "ICEDQ_REALM": "iam.icedq",
        "ICEDQ_CLIENT_ID": "<your-client-id>",
        "AUTH_TYPE": "access_token",
        "TOKENS_PATH": "/path/to/tokens.json",
        "ICEDQ_ORG_ID": "<your-org-id>",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

TOKENS_PATH must point to a JSON file shaped like:

{
  "accessToken": "<JWT access token>",
  "refreshToken": "<JWT refresh token>"
}

The server reads this file on startup, uses the access token until it expires, and automatically refreshes it (rewriting the file) using the refresh token — no browser or password prompt involved. This is the recommended option for headless automation, CI, or server-to-server integrations where interactive login isn't possible.

Setup Guides

Choose your AI client for a step-by-step walkthrough:

Client	Guide
Claude Desktop	Installation in Claude Desktop
VS Code + Copilot Chat	VS Code Setup
VS Code + Claude Code	Claude Code Setup
Cursor	Cursor Setup

For authentication configuration, see the Authentication Guide.

---

Usage Examples

1. Explore Your Data

Prompt: List my iceDQ workspaces and show the connections

Response:

Found 2 workspaces:

• Production_DQ (Active)
• Development_DQ (Active)

Production_DQ has 3 connections:

• SQL_Server_Production (SqlServer) - ACTIVE
• Snowflake_Warehouse (Snowflake) - ACTIVE
• Azure_DataLake (AzureBlob) - ACTIVE

2. Profile Data Quality

Prompt: Fetch sample data from the Customers table and suggest quality checks

Response:

Fetched 10 rows from dbo.Customers. Profiling results:

Email: 33% null, valid email pattern in 60% of values FirstName: 1 empty value detected Status: 2 distinct values: Active, Inactive CreatedDate: Date pattern yyyy-MM-dd detected

Suggested checks:

1. Email - NotNull (33% nulls detected)
2. Email - Format: Email pattern
3. FirstName - NotNull (empty values found)
4. Status - ValidValues: Active, Inactive
5. CreatedDate - Date format: yyyy-MM-dd

3. Create a Validation Rule

Prompt: Create a validation rule called Customer_Quality_Checks with those suggested checks

Response:

Rule created successfully! Rule ID: rule-12345678-abcd-ef01-2345-678901234567 Name: Customer_Quality_Checks Checks: 5 checks configured Status: Published (ready to execute)

4. Detect Duplicates

Prompt: Check for duplicate emails in the Customers table

Response:

Duplicate detection rule created! Rule ID: rule-aabbccdd-1122-3344-5566-778899001122 Name: Customer_Email_Duplicates Columns: Email Status: Published (ready to execute)

5. Compare Data Across Sources

Prompt: Compare row counts between SQL Server Orders table and Snowflake FACT_ORDERS

Response:

Checksum rule created! Rule ID: rule-eeff0011-2233-4455-6677-889900aabbcc Name: Orders_vs_FACT_ORDERS_Checksum Source: SQL_Server_Production / dbo.Orders Target: Snowflake_Warehouse / DATAOPS_DW.FACT_ORDERS Check: SOURCE_COUNT - TARGET_COUNT == 0

6. Execute and Monitor

Prompt: Execute the Customer_Quality_Checks rule and show results

Response:

Execution completed! Status: Success Source rows: 1,000 Exceptions: 5 rows failed validation Exit code: 5

Breakdown:

• Email_NotNull: 3 failures
• Email_Format: 1 failure
• FirstName_NotNull: 1 failure

7. Analyze Rule Execution History

Prompt: Analyze all rules executed last month and give me a summary of passed, failed, and errored rules

Response:

Execution Summary — Last 30 Days

Total rules executed: 24

Passed: 17 rules

• Customer_Quality_Checks — 0 exceptions
• Orders_NotNull_Check — 0 exceptions
• Product_Format_Validation — 0 exceptions
• ... 14 more

Failed: 5 rules (exceptions found)

• Email_Duplicate_Check — 312 exceptions
• Orders_vs_FACT_ORDERS_Checksum — count mismatch detected
• Address_Format_Check — 87 exceptions
• ... 2 more

Errored: 2 rules (execution did not complete)

• Inventory_Recon_Rule — connection timeout
• Sales_Pushdown_Check — query syntax error

---

Agent skills

The server ships eight skills under skills/ (also packaged into the Claude plugin). Each skill is self-contained; shared references are edited in skills/_shared/ and copied with sync.sh.

Skill	Use when
icedq-suggest-checks	You want recommendations, coverage analysis, or a testing plan
icedq-author-rules	You already know the checks (or another skill handed over a rule spec)
icedq-compare-datasets	Migration certification or ongoing reconciliation between two datasets
icedq-mapping-doc-rules	Checks should be derived from a mapping document
icedq-etl-code-rules	Checks should be derived from ETL/SQL/dbt code
icedq-api-testing	The source is a named REST API (validation or recon against a backend)
icedq-run-and-report	Execute existing rules/workflows and read exception reports
icedq-schedule-and-monitor	Automate existing rules and inspect schedule history

See skills/COMPATIBILITY.md for the skill ↔ server version policy, and evals/README.md for the evaluation suite.

Complete Tool Reference

Full names, parameters, and category counts are in Tools References (49 tools). Summary:

Discovery & Exploration (11 tools)

Tool	Description
List Workspaces	List all workspaces in your iceDQ instance
List Connections	List data source connections in a workspace
Test Connection	Test connectivity for a data source connection
List Folders	List folders for organizing rules, workflows, schedules, and parameters
List Rules	Search and filter rules by folder, name, state, or type
List Workflows	List all workflows in a workspace
List Schedules	List all schedules in a workspace
Get Database Metadata	Get connection details and database capabilities
List Connection Metadata	Navigate databases, schemas, tables, or columns for a connection
Get Rule	Get full rule configuration, checks, and metadata
Get Guidance	Get step-by-step workflow guidance before starting a multi-step task

Data Analysis & Profiling (6 tools)

Tool	Description
Fetch Sample Data	Fetch real rows from a database table or custom SQL query
List Files	List files available in a flat-file connection (Azure Blob, S3, local)
Fetch File Sample Data	Fetch sample data from a file (CSV, Parquet, Excel, JSON, XML) and register its schema
Fetch API Sample Data	Fetch sample data from a REST API endpoint and register its schema
Profile Data	Analyze sample data for nulls, patterns, types, uniqueness
Suggest Quality Checks	AI-powered check recommendations from profiled data

Rule Creation (6 tools)

Tool	Description
Create Validation Rule	Row-level validation with NotNull, Format, ValidValues, Length, Date, and Custom checks
Create Duplicate Rule	Duplicate detection on single or composite columns
Create Pushdown Rule	SQL-driven aggregate and cross-table validation
Create Checksum Rule	Cross-source numeric comparison (COUNT, SUM, AVG)
Analyze Recon Mapping	AI-powered join key and column mapping suggestions
Create Recon Rule	Row-level cross-source reconciliation

Rule Management (3 tools)

Tool	Description
Update Rule	Add/remove checks, change source table or SQL
Move Rules or Workflows	Move rules or workflows between folders (batch supported, async)
Check Task Status	Monitor async operations such as moves

Custom Functions (3 tools)

Tool	Description
Manage Custom Function	Create or update a Java/Groovy UDF (Evaluator or Processor type)
List Custom Functions	List all UDFs in a workspace
Get Custom Function	Get the full source code and metadata of a UDF

Workflows (2 tools)

Tool	Description
Create Workflow	Chain multiple rules into a sequential workflow
Update Workflow Rules	Add or remove rules from an existing workflow

Schedules (3 tools)

Tool	Description
Create Schedule	Schedule automated rule/workflow execution
Modify Schedule	Update schedule timing, recurrence, or configuration
Add Rules/Workflows to Schedule	Add additional rules/workflows to an existing schedule

Parameters (4 tools)

Tool	Description
List Parameters	List and search parameters in a workspace
Get Parameter	Get full details of a parameter, including key-value pairs
Create or Update Parameter	Create a new parameter or update an existing one
Parse CSV and Create Parameter	Import a parameter's key-value pairs from a CSV file

Data Warehouse Queries (3 tools)

Tool	Description
Datawarehouse Query Schema	Discover datasets, columns, metrics, and joins available for querying
Datawarehouse Query Executor	Execute structured, schema-validated data warehouse queries
Validate and Explain Structured Query	Dry-run a query and preview generated SQL before executing

Execution & Monitoring (7 tools)

Tool	Description
Execute Rules or Workflows	Execute one or more rules or workflows on demand
Execute Schedule	Trigger a schedule on demand
Get Rule/Workflow Run History	View execution history for a rule or workflow
Get Workflow Run Status or Result	Track progress or fetch detailed per-activity results of an execution
Get Scheduler Runs History	View execution history for a schedule
Get Checks Exception Report	View row-level failure details for a rule run
Get Exception Report URL	Get the iceDQ UI URL to view the full exception report for a rule or workflow instance

Organization (1 tool)

Tool	Description
Create Folder	Create folders to organize rules, workflows, schedules, and parameters

---

Troubleshooting

Issue	Solution
Organization ID required	Add your Organization ID in configuration (e.g. org-icedq)
SSL certificate verification failed	Claude Desktop: uncheck Verify SSL. npx: set VERIFY_SSL to false (self-signed certs only). Prefer NODE_OPTIONS: --use-system-ca for corporate CAs
No workspaces returned	Verify credentials, check base URL, ensure user has workspace access
Sample data not returning	Check connection is ACTIVE, verify table name (case-sensitive), check permissions
Authentication failures	Verify client ID, client secret, username, and password are correct

Enable Debug Mode

For detailed troubleshooting, enable verbose logging:

• Claude Desktop (extension): Settings → Extensions → iceDQ → Configure → Debug Mode: ON
• npx / manual configuration: add "DEBUG": "true" to the env block of your MCP configuration

Claude Desktop extension log locations:

• Windows: %APPDATA%\Claude\Logs\extensions\
• macOS: ~/Library/Logs/Claude/extensions/

---

Security & Privacy

How Your Data is Protected

• Credentials are provided through your AI client's configuration and sent only to your iceDQ instance — the Claude Desktop extension stores them in your operating system keychain
• All communication uses HTTPS with OAuth 2.0 authentication
• Data flows directly between your AI client and your iceDQ instance -- no third parties
• No telemetry or tracking of any kind
• No data persistence by the MCP server beyond the active session, except tokens you opt into (device_flow OS keychain / access_token TOKENS_PATH)
• SSL verification is enabled by default

Privacy Policy

Data collection: None. The MCP server collects no usage data, telemetry, or analytics.

Usage & storage: All data flows directly between your AI client and your iceDQ instance. The MCP server holds credentials and API tokens in memory for the active session. In device_flow mode, tokens are cached in the OS keychain (with a local file fallback). In access_token mode, tokens are persisted to the TOKENS_PATH file you supply. Nothing is written anywhere else.

Third-party sharing: None. No data is transmitted to Anthropic, iceDQ, or any third party beyond your own iceDQ instance.

Data retention: The MCP server retains nothing after the session ends. Token files (if used) remain on your local machine under your full control and can be deleted at any time.

Contact: getsupport@icedq.com

For full details, see: https://icedq.com/privacy-policy

---

Support

Need help? We're here for you.

Channel	Contact
Email	getsupport@icedq.com
Documentation	docs.icedq.com
Website	icedq.com

---