MCP

Model Context Protocol - Connecting Coalesce Quality to AI applications

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with external data sources and tools. MCP is supported by various AI tools including Claude Desktop, Cursor, VS Code, and other AI development environments.

For detailed information about MCP, see:

• Anthropic’s MCP Documentation
• Introduction to MCP

Getting Started

MCP works out of the box — no workspace configuration needed. Just add the server to your AI client and authenticate:

Client Setup

Use the MCP server URL for your region:

Region	MCP Server URL
US	https://mcp.us.synq.io/mcp
EU	https://mcp.synq.io/mcp

Claude Code

Run in your terminal:

# US region
claude mcp add synq --transport http https://mcp.us.synq.io/mcp

# EU region
claude mcp add synq --transport http https://mcp.synq.io/mcp

Claude Desktop / claude.ai

Go to Settings → Connectors → Add custom connector and enter the MCP server URL for your region. This works in both the Claude Desktop app and on claude.ai.

Alternatively, add the following to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "synq": {
      "url": "https://mcp.us.synq.io/mcp"
    }
  }
}

For EU region, use https://mcp.synq.io/mcp instead.

Cursor

Open Settings → MCP → Add new MCP Server and add an HTTP server with this configuration (or paste it into ~/.cursor/mcp.json):

{
  "mcpServers": {
    "synq": {
      "url": "https://mcp.us.synq.io/mcp"
    }
  }
}

For EU region, use https://mcp.synq.io/mcp instead.

VS Code

Add the following to .vscode/mcp.json (workspace) or your user MCP config:

{
  "servers": {
    "synq": {
      "type": "http",
      "url": "https://mcp.us.synq.io/mcp"
    }
  }
}

For EU region, use https://mcp.synq.io/mcp instead. Requires VS Code 1.102 or newer (built-in MCP support).

Codex CLI

Run in your terminal:

# US region
codex mcp add synq --url https://mcp.us.synq.io/mcp

# EU region
codex mcp add synq --url https://mcp.synq.io/mcp

Codex stores the server under ~/.codex/config.toml. On the first run (codex), Codex opens your browser for the OAuth flow — approve on the consent screen and the session starts with Coalesce Quality tools available.

Gemini CLI

Run in your terminal:

# US region
gemini mcp add synq --transport http https://mcp.us.synq.io/mcp

# EU region
gemini mcp add synq --transport http https://mcp.synq.io/mcp

Use -s user to save the server globally instead of in the current project. On the first tool call, Gemini opens your browser for the OAuth flow; once approved, Coalesce Quality tools are available in the session.

Other Clients

Any client that speaks the MCP Streamable HTTP transport can connect. Point it at the regional URL and let it drive the OAuth flow:

https://mcp.us.synq.io/mcp

For EU region, use https://mcp.synq.io/mcp instead.

Authentication

Coalesce Quality MCP uses OAuth2 with PKCE for secure authentication. This is the recommended way to connect — no API keys or tokens need to be pasted anywhere, and every action the AI takes is attributed to you, with a via MCP badge on the actor chip so it’s clear the change came from an AI assistant rather than the app.

The flow is fully automatic:

1. When your AI client connects for the first time, your browser will open automatically
2. If you are already logged in to Coalesce Quality, the consent screen appears directly. Otherwise, you will be asked to log in first.
3. Select the permission level you want to grant (see Permissions below)
4. Click Approve to authorize

All actions performed through MCP are tracked as done on behalf of the authenticated user, and carry a via MCP marker so the audit trail distinguishes AI-driven actions from ones performed directly in the app.

Static tokens (legacy)

Long-lived workspace tokens (prefixed st-…) created under Settings → API still work with the MCP server — pass one as a Bearer token in the Authorization header of the MCP connection. Use this only when OAuth is not an option (for example, headless automation without a real user, or when user API access is disabled for the workspace).

We recommend OAuth for all interactive AI clients: actions are attributed to the real user rather than to a shared service identity, tokens can be revoked per-user, and the scopes granted match what that user’s role already allows.

Permissions

During authorization, you choose what level of access to grant. The available permission scopes on the consent screen are determined by your user role in the workspace — you will only see options that your role allows.

Permission	What it allows
Read-only access	Search and browse entities, view schemas and lineage, inspect issues and incidents, check monitor status, review execution history, query data, and profile columns. No changes are made.
Write access	Everything in read-only, plus acting on your behalf — manage issues, declare and close incidents, add comments, and more.
Deploy access	Create and configure automatic and custom monitors for data quality checks.

The set of MCP tools available to your AI assistant depends on the permissions you grant during authorization. For example, if you only grant read-only access, tools that modify data (like managing issues or deploying monitors) will not be available.

Disabling User API Access

Workspace admins can prevent users from authorizing third-party applications (including MCP clients) to access the Coalesce Quality API via OAuth. The toggle lives in Settings → Workspace and can be flipped on or off at any time by a user with the admin role — individual users do not need to take any action when the setting changes.

While this is enabled:

• New OAuth consent attempts from MCP clients are rejected with an explanatory message on the consent screen.
• Existing OAuth tokens issued to users stop working.
• Workspace-provisioned long-lived tokens (st-…) and client credentials continue to work — use those if you need programmatic access in this mode.

Turning the setting back off immediately restores the OAuth path; users will need to re-authorize their MCP client the next time it connects.

Coalesce Quality MCP Tools

Once connected, your AI assistant has access to a wide range of tools for working with your data infrastructure. The tables below group them by purpose.

Discovery and Search

Tool	Description
search_entities	Search for entities by name, description, and other metadata with optional filtering by entity types
sample_entities	Get entity count sampling by type for search queries to understand distribution before detailed searches
list_annotations	List all available annotations with their usage counts across entities

Core Entity Operations

Tool	Description
get_entity_details	Retrieve detailed information about a specific data entity including properties, metadata, and current state
batch_entity_details	Get details for multiple entities simultaneously - more efficient than multiple individual calls
get_schema	Retrieve schema definition including column names, types, and constraints for table-like entities
get_database_coordinates_from_entity	Retrieve physical DWH coordinates (dialect, connection, instance, database, schema, object) for table entities
get_entity_from_database_coordinates	Map SQL table references (fully/partially/unqualified) to Coalesce Quality entity IDs
get_code	Access the latest version of source code that defines or implements data entities (SQL definitions, dbt models, etc.)

Data Lineage Analysis

Comprehensive Lineage

Tool	Description
get_lineage	Advanced dependency analysis with directional control (upstream, downstream, or both) and configurable depth

Upstream Analysis

Tool	Description
get_upstream_dependencies	Find all upstream dependencies with configurable traversal distance
get_immediate_upstream_dependencies	Find only direct upstream dependencies for quick analysis
get_upstream_sources	Trace data lineage to find original data sources (dbt sources, SQLMesh external models, Coalesce sources)

Downstream Analysis

Tool	Description
get_downstream_dependencies	Find all downstream dependencies with configurable traversal distance
get_immediate_downstream_dependencies	Find only direct downstream dependencies for quick analysis

Cross-Entity Analysis

Tool	Description
get_common_upstream_dependencies	Find shared dependencies between two entities using connected components analysis

Orchestration

Tool	Description
get_orchestration	Get orchestration relationships for entities - shows what orchestrates them (upstream) and what they orchestrate (downstream)

Issue and Incident Management

Tool	Description
list_open_issues	List all open issues currently requiring attention with optional entity filtering
list_open_incidents	List all currently open incidents that need attention or resolution with optional entity filtering
get_issue	Return the core issue record for a specific issue ID (status, severity, trigger entity)
get_issue_details	Return the issue record plus the first page of comments and — for monitor-triggered issues — the monitor configuration and schema of the monitored entity. Prefer this over get_issue when you need context to reason about the issue
get_issue_comments	Get comments and discussions on issues if available
get_incident_details	Retrieve detailed information about a specific incident by ID, including attached issues, state, and comment timeline
list_history	Find historical incidents and issues to identify patterns and recurring problems

Impact Analysis

Tool	Description
get_entity_impact	Get impact analysis showing all entities and systems affected if there was an issue on the entity
get_issue_impact	Get impact analysis showing all entities and systems affected by a specific issue

Data Quality and Monitoring

Tool	Description
list_checks	Retrieve all data quality checks configured for a specific entity (direct and inherited)
get_monitor	Retrieve detailed information about a specific monitor including configuration and status
get_monitor_predictions	Return recent model predictions for a monitor with expected vs actual values and confidence bands — useful for diagnosing miscalibrated anomaly detection
get_entity_metrics	Return raw metric timeseries (row counts, freshness, etc.) for an entity; resolves logical assets (e.g., dbt models) to their underlying physical tables

Executions

Tool	Description
get_latest_executions	Get the most recent execution for each specified entity (monitors, dbt models, airflow tasks, etc.)
list_executions	List execution history for specific entities with filtering by time range, status, and execution type
batch_executions	Get detailed information for specific executions by their IDs
summarise_executions	Get aggregated execution statistics - counts by type and status, time ranges, and latest execution per entity

SQL Generation for Data Analysis

These tools generate the SQL that Coalesce Quality would run to analyse data, but the MCP server does not execute queries against your warehouse. The response includes the full executedSql — run it yourself (or let your AI client run it through a separate warehouse connection) to get actual results. This keeps your data inside your own warehouse and avoids giving the MCP server any standing database credentials.

Tool	Description
execute_monitor	Generate the SQL a monitor would run, including any extra segmentation, WHERE clauses, or time filters you pass in. Similar in spirit to get_code but for the check SQL — get_code returns the asset’s definition, execute_monitor returns the query the monitor executes against that asset
profile_columns	Generate SQL that computes statistics for specific columns (supports String, Numeric, and Time types)
sample_column_values	Generate SQL that returns the frequency distribution of values for specific columns, with optional time-based filtering

Change Tracking and History

Database Changes

Tool	Description
list_database_changes	Retrieve history of schema and SQL definition changes for specific entities
get_database_change_details	Return full change details for specific change IDs

Git Integration

Tool	Description
list_commits	List commits that affect a specific entity, providing git history and change information
get_commit_diff	Retrieve exact diff content of specific commit changes with optional path filtering

Write Actions

The tools in this section modify workspace data and require Write access (for issue/incident actions) during OAuth consent. If the user granted only read-only access, these tools will not appear in the client.

Tool	Required scope	Description
set_issue_status	Write	Set the status of a single issue (e.g., mark as expected behaviour, fixed upstream, no action needed). An optional note is posted as a comment to preserve the audit trail
add_comment	Write	Post a Markdown comment on an issue or incident, attributed to the authenticated user
create_incident	Write	Create a new incident grouping one or more related issues under a shared name for coordinated investigation
update_incident	Write	Edit an existing incident — rename, change state, reassign owner, or attach/detach issues in a single call

Utilities

Tool	Description
batch_urls	Generate Coalesce Quality application URLs for multiple entities and issues for easy navigation
submit_feature_request	Submit a feature request or product feedback to the Coalesce Quality team from your AI assistant