iceDQ 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:

Related MCP server: MCP Data Visualization Server

System Requirements

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

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:

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.

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)

Data Analysis & Profiling (6 tools)

Rule Creation (6 tools)

Rule Management (3 tools)

Custom Functions (3 tools)

Workflows (2 tools)

Schedules (3 tools)

Parameters (4 tools)

Data Warehouse Queries (3 tools)

Execution & Monitoring (7 tools)

Organization (1 tool)

Troubleshooting

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.