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

Node management

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

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