Coalesce MCP Server

An MCP (Model Context Protocol) server that gives Claude direct access to your Coalesce data pipelines. Ask Claude to investigate failures, inspect nodes, and understand your pipeline in plain English — without leaving your chat.

What it does

Failure investigation — the primary use case. Ask Claude:

• "Why did run 95011 fail?"
• "What failed in the last hour?"
• "Show me the error and SQL from the failing node"

Claude will call investigate_failure, surface the exact error message, the SQL that failed, and which downstream nodes were blocked — all in one response.

Node inspection — browse and read your workspace:

• "Show me the columns and transforms for node X"
• "What does this staging table look like?"

Node editing — modify workspace nodes programmatically (disable with COALESCE_READONLY_MODE=true):

• "Update the SQL on this node"
• "Create a new stage node"
• "Apply the TRY_CAST fix to the failing column"

Quick start

1. Install

# Recommended
uvx --from coalesce-mcp coalesce-mcp-server

# Or install globally
uv tool install coalesce-mcp

2. Get your API token

1. Log into Coalesce
2. Go to Settings → API Tokens
3. Create a token and copy it

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coalesce": {
      "command": "uvx",
      "args": ["--from", "coalesce-mcp", "coalesce-mcp-server"],
      "env": {
        "COALESCE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop. You're done.

Tools

Failure investigation

Tool	Description
investigate_failure	Best starting point. Run metadata + failed nodes (with error messages and SQL) + downstream blocked nodes in one call.
list_failed_runs	List recent failed runs. Use this to find a run_id to investigate.
list_job_runs	List all recent runs with optional filters (status, environment, limit).
get_run_results	Node-level results for a run — failures and blocked nodes only, succeeded nodes omitted.
get_run	Full metadata for a specific run.
get_run_status	Live status via the scheduler endpoint.
get_job_details	Run metadata + extracted errors combined.

Node management

Tool	Description
list_workspace_nodes	List all nodes in a workspace.
list_environment_nodes	List all deployed nodes in an environment.
get_workspace_node	Full node config — columns, transforms, source mappings, SQL.
get_environment_node	Same as above for deployed (production) nodes.
create_workspace_node	Create a new node with defaults.
set_node	Full replacement update of an existing node. Read first, then write.
patch_node_field	Surgical single-field update (e.g. fix one column transform). Handles fetch-modify-replace internally.

Recommended investigation workflow

1. list_failed_runs          → find a run_id
2. investigate_failure       → root cause + downstream impact
3. get_workspace_node        → inspect the failing node's SQL and transforms
4. patch_node_field          → apply the fix (with your approval)

Configuration

Variable	Default	Description
COALESCE_API_TOKEN	required	Bearer token from Coalesce Settings → API Tokens
COALESCE_BASE_URL	https://app.coalescesoftware.io/api/	Override for on-prem deployments
COALESCE_READONLY_MODE	false	Set true to hide create_workspace_node, set_node, and patch_node_field

Switching Between Coalesce Accounts

The simplest way to switch accounts is to update COALESCE_API_TOKEN in your .env file.

Copy .env.example to .env and fill in your token:

cp .env.example .env
# Edit .env and set COALESCE_API_TOKEN to your token

To connect to a different account, replace the token value in .env with the new account's token, then restart your MCP host (Claude Desktop or Cortex CLI).

# .env
COALESCE_API_TOKEN=your-new-account-token-here

Never commit .env to git. It is listed in .gitignore. Use .env.example as a reference template instead.

Snowflake Cortex CLI

Add this to ~/.snowflake/cortex/mcp.json, with your token pasted in directly:

{
  "mcpServers": {
    "coalesce": {
      "command": "/path/to/coalesce-mcp-server",
      "env": {
        "COALESCE_API_TOKEN": "your-token-here",
        "COALESCE_READONLY_MODE": "true"
      }
    }
  }
}

Note: The Cortex CLI does not expand shell variables — paste the token value directly rather than using ${COALESCE_API_TOKEN}.

Set COALESCE_READONLY_MODE=true if your agent role is read-only.

Development

git clone https://github.com/JarredR092699/coalesce-mcp.git
cd coalesce-mcp

# Install with dev dependencies
uv sync

# Run tests
uv run pytest

# Install locally
uv tool install . --force

Requirements

• Python 3.10+
• A Coalesce account with API access

License

MIT — see LICENSE

Links

• Issues
• Coalesce API docs
• Model Context Protocol