MCP server for Coalesce. Built for Snowflake Cortex Code (CoCo) - with first-class support for every other MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf). Manage nodes, pipelines, environments, jobs, and runs, and drive the local-first Coalesce CLI from the same server: validate a project, preview DDL/DML, plan a deployment, and apply it to a cloud environment.
Each link below opens a short install guide with a click-to-install button (where supported) and the manual config.
[!TIP]
❄️ Snowflake Cortex Code + coalesce-transform-mcp. CoCo is Snowflake's AI coding CLI - it already knows your warehouse, role, and data. Drop this MCP in and an agent can plan pipelines, create nodes, run DML, and verify results in a single session, all under Snowflake's auth model. Install in Cortex Code →
❄️ Install in Snowflake Cortex Code (CoCo)
Why this pairing? Cortex Code is Snowflake's AI coding CLI - it already authenticates to your warehouse, runs under your Snowflake role, and has native tools for querying live data. Add coalesce-transform-mcp and a single agent session can plan pipelines, create nodes, run DML, and verify results against real rows without leaving the terminal.
Drop the env block if you're using ~/.coa/config - Cortex Code and Coalesce can both pick the token up from the same profile. Full walkthrough: docs/installation-guides/cortex-code.md.
Claude Code does expand ${VAR} from your shell env at load time - .mcp.json can stay safely committed to git with variable references. Omit the env block if using ~/.coa/config.
Install in Claude Desktop
No deeplink yet - paste manually.
File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Claude Desktop does not expand ${VAR} - paste the literal token, or drop the env block and use ~/.coa/config. Fully quit Claude Desktop (Cmd+Q) and relaunch after editing.
Windsurf does not expand ${VAR} - paste the literal token, or drop the env block and use ~/.coa/config. Restart Windsurf after editing.
[!TIP]
🚀 Just installed?
Just say "help me get set up" — or run /coalesce-setup. Your agent will check your credentials and project setup, then walk you through fixing whatever's missing.
Skills
Skills are editable markdown that shapes how the agent reasons about your Coalesce project. Ship your team's naming conventions, grain definitions, and layering patterns as context - every agent on the server instantly picks them up. No fine-tuning, no prompt engineering, just markdown you edit and commit.
Set COALESCE_MCP_SKILLS_DIR to make skills editable on disk. Each skill resolves to default content, user-augmented content, or a full user override - see docs/context-skills.md for the resolution order and customization walkthrough.
25 skills, grouped into 6 families:
Foundations — the shared context every agent starts with
overview - General Coalesce concepts, response guidelines, and operational constraints
tool-usage - Best practices for tool batching, parallelization, and SQL conversion
list_workspace_node_types - List distinct node types observed in current workspace nodes
Jobs, subgraphs, runs
list_environment_jobs - List all jobs for an environment
get_environment_job - Get details of a specific job
get_workspace_subgraph - Get details of a specific subgraph by UUID (the public API has no subgraph list endpoint — look up UUIDs via the repo's subgraphs/ folder or the local cache populated on create)
list_runs - List runs with optional filters
get_run - Get details of a specific run
get_run_results - Get results of a completed run
get_run_details - Run metadata plus results in one call
create_environment - Create a new environment within a project
delete_environment - Delete an environment ⚠️
create_project - Create a new project
update_project - Update a project
delete_project - Delete a project ⚠️
list_git_accounts - List all git accounts
get_git_account - Get git account details
create_git_account - Create a new git account
update_git_account - Update a git account
delete_git_account - Delete a git account ⚠️
Users & roles — assign and remove org, project, and environment roles
list_org_users - List all organization users
get_user_roles - Get roles for a specific user
list_user_roles - List all user roles
set_org_role - Set organization role for a user
set_project_role - Set project role for a user
delete_project_role - Remove project role from a user ⚠️
set_env_role - Set environment role for a user
delete_env_role - Remove environment role from a user ⚠️
Cache, skills & setup — local snapshots, customizable skills, and setup diagnostics
Cache snapshots
cache_workspace_nodes - Fetch every page of workspace nodes, write a full snapshot, and return cache metadata
cache_environment_nodes - Fetch every page of environment nodes, write a full snapshot
cache_runs - Fetch every page of run results, write a full snapshot
cache_org_users - Fetch every page of organization users, write a full snapshot
clear_data_cache - Delete all cached snapshots, auto-cached responses, and plan summaries ⚠️
Skills & setup
personalize_skills - Export bundled skill files to a local directory for customization
diagnose_setup - Stateless probe reporting configured setup pieces; pairs with the /coalesce-setup MCP prompt
🧰 coa_doctor - Check config, credentials, and warehouse connectivity end-to-end for a local project
🧰 coa_describe - Fetch a section of COA's self-describing documentation by topic + optional subtopic (also available as coalesce://coa/describe/* resources)
Snowflake credentials - only if you plan to use run tools or coa_create/coa_run (see Credentials)
Install footprint is ~76 MB unpacked (the bundled @coalescesoftware/coa CLI ships its own runtime; the MCP tarball itself is under 1 MB)
1. Clone your project. If your team already has a Coalesce project in Git, clone it locally - the bundled coa CLI operates on a project directory, so most local create/run tools require one on disk:
git clone <your-coalesce-project-repo-url>
cd my-project
Don't have a Git-linked project yet? In the Coalesce UI, open your workspace → Settings → Git and connect a repo (or create one via your Git provider and paste the URL). Coalesce will commit the project skeleton on first push; clone that repo locally once it's populated.
V1 vs V2 - the format is pinned by fileVersion in data.yml. V1 (fileVersion: 1 or 2) stores each node as a single YAML file with columns, transforms, and config inline. V2 (fileVersion: 3) is SQL-first: the node body lives in a .sql file using @id / @nodeType annotations and {{ ref() }} references, with YAML retained for config. New projects default to V2; existing V1 projects keep working unchanged.
Point the MCP at this directory by setting repoPath in ~/.coa/config or COALESCE_REPO_PATH in your env block.
2. Create workspaces.yml. This file is required for coa_create / coa_run and their dry-run variants. It maps each storage location declared in locations.yml to a physical database + schema for local development. It's typically gitignored (per-developer), so cloning the project does not give it to you - you have to create it.
The /coalesce-setup prompt detects a missing workspaces.yml and walks you through it. If you'd rather do it directly, pick one of:
Ask your agent to bootstrap it (easiest): prompt the agent to call the coa_bootstrap_workspaces tool (it needs confirmed: true, so the agent will ask before running).
[!WARNING]
The generated file contains placeholder values. The bootstrap tool seeds database/schema with defaults that won't match your real warehouse. Ask the agent to open the file with you and replace every placeholder before calling coa_create / coa_run - otherwise the generated DDL/DML will target the wrong (or non-existent) database.
Hand-write it. Ask the agent to fetch the authoritative schema via the coa_describe tool (topic: "schema", subtopic: "workspaces") - no top-level wrapper, no fileVersion.
Example workspaces.yml
# workspaces.yml - keys are workspace names; `dev` is the default if --workspace is omitted
dev:
connection: snowflake # required - name of the connection block COA should use
locations: # optional - one entry per storage location name from locations.yml
SRC_INGEST_TASTY_BITES:
database: JESSE_DEV # required
schema: INGEST_TASTY_BITES # required
ETL_STAGE:
database: JESSE_DEV
schema: ETL_STAGE
ANALYTICS:
database: JESSE_DEV
schema: ANALYTICS
Ask your agent to verify the setup - e.g. "Run coa_doctor on my project and summarize the results." It checks data.yml, workspaces.yml, credentials, and warehouse connectivity end to end.
3. Pick an auth path:
Option A - env var
Option B - reuse ~/.coa/config
Simplest for first-time MCP users. Generate a COALESCE_ACCESS_TOKEN from Coalesce → Deploy → User Settings, then include it in your client config:
4. Install the server via one of the Quick Start paths above.
5. Restart your client, then run the /coalesce-setup prompt to verify everything is wired up.
If you have more than one Coalesce environment to manage, see Multiple environments.
Credentials
The server reads credentials from two sources and merges them with env-wins precedence - a matching env var always overrides the profile value, so you can pin a single field per session without editing the config file. Call diagnose_setup to see which source supplied each value.
Source 1: ~/.coa/config (shared with the coa CLI)
COA stores credentials in a standard INI file. You create it by hand, or let coa write it as you use the CLI. The MCP reads the profile selected by COALESCE_PROFILE (default [default]) and maps the keys below onto their matching env vars.
[default]
token=<your-coalesce-refresh-token>
domain=https://your-org.app.coalescesoftware.io
snowflakeAccount=<your-snowflake-account> # e.g., abc12345.us-east-1 - required by coa CLI
snowflakeUsername=YOUR_USER
snowflakeRole=YOUR_ROLE
snowflakeWarehouse=YOUR_WAREHOUSE
snowflakeKeyPairKey=/Users/you/.coa/rsa_key.p8
snowflakeAuthType=KeyPair
orgID=<your-org-id> # optional; fallback for cancel-run
repoPath=/Users/you/path/to/repo # optional; for repo-backed tools
cacheDir=/Users/you/.coa/cache # optional; per-profile cache isolation
[staging]
# …additional profiles; select with COALESCE_PROFILE
Key mapping - each profile key maps to an env var of the same concept:
Profile key
Env var
token
COALESCE_ACCESS_TOKEN
domain
COALESCE_BASE_URL
snowflake* (all keys)
SNOWFLAKE_* (matching suffix)
orgID
COALESCE_ORG_ID
repoPath
COALESCE_REPO_PATH
cacheDir
COALESCE_CACHE_DIR
Notes:
snowflakeAuthType is read by COA itself (no env var) - include it when using key-pair auth.
orgID, repoPath, and cacheDir are MCP-specific - the COA CLI ignores them.
Only the fields the MCP needs are shown above. COA's config supports many more - run npx @coalescesoftware/coa describe config for the authoritative reference. Unknown keys are ignored.
If ~/.coa/config doesn't exist the server runs env-only - startup never fails on a missing or malformed profile file; it just logs a stderr warning.
Source 2: env vars in your MCP config
Variable
Description
Default
COALESCE_ACCESS_TOKEN
Bearer token from the Coalesce Deploy tab. Optional when ~/.coa/config provides a token.
—
COALESCE_PROFILE
Selects which ~/.coa/config profile to load.
default
COALESCE_BASE_URL
Region-specific base URL.
https://app.coalescesoftware.io (US)
COALESCE_ORG_ID
Fallback org ID for cancel-run. Also readable from orgID in the active ~/.coa/config profile.
—
COALESCE_REPO_PATH
Local repo root for repo-backed tools and pipeline planning. Also readable from repoPath in the active ~/.coa/config profile.
—
COALESCE_CACHE_DIR
Base directory for the local data cache. When set, cache files are written here instead of the working directory. Also readable from cacheDir in the active ~/.coa/config profile.
—
COALESCE_MCP_AUTO_CACHE_MAX_BYTES
JSON size threshold before auto-caching to disk.
32768
COALESCE_MCP_LINEAGE_TTL_MS
In-memory lineage cache TTL in milliseconds.
1800000
COALESCE_MCP_MAX_REQUEST_BODY_BYTES
Max outbound API request body size.
524288
COALESCE_MCP_READ_ONLY
When true, hides all write/mutation tools during registration. Only read, list, search, cache, analyze, review, diagnose, and plan tools are exposed.
false
COALESCE_MCP_SKILLS_DIR
Directory for customizable AI skill resources. When set, reads context resources from this directory and seeds defaults on first run. Users can augment or override any skill.
—
Snowflake credentials (run tools only)
start_run, retry_run, run_and_wait, retry_and_wait, and the warehouse-touching COA tools (coa_create, coa_run) need Snowflake credentials. These normally come from ~/.coa/config. Override any field via env var:
Variable
Required
Description
SNOWFLAKE_ACCOUNT
Yes
Snowflake account identifier (e.g., abc12345.us-east-1). Required by the local coa CLI and coa doctor; not used by the MCP's REST run path.
SNOWFLAKE_USERNAME
Yes
Snowflake account username
SNOWFLAKE_KEY_PAIR_KEY
No
Path to PEM-encoded private key (required if SNOWFLAKE_PAT not set)
SNOWFLAKE_PAT
No
Snowflake Programmatic Access Token (alternative to key pair)
SNOWFLAKE_KEY_PAIR_PASS
No
Passphrase for encrypted keys
SNOWFLAKE_WAREHOUSE
Yes
Snowflake compute warehouse
SNOWFLAKE_ROLE
Yes
Snowflake user role
"Required" means one of env OR the matching ~/.coa/config field must supply the value. SNOWFLAKE_PAT is env-only - COA's config uses snowflakePassword for Basic auth (a different concept), which this server deliberately doesn't read.
Field-level overrides
Pin a profile but override one field without editing the config file
Reads: "use the [staging] profile, but override its snowflakeRole."
Multiple environments
Register dev / staging / prod as separate namespaced servers
If you work across several Coalesce environments (dev/staging/prod, or multiple orgs), register the package once per profile under distinct server names:
Namespaced tools. The client surfaces coalesce-prod__* vs coalesce-dev__*, so an agent can't accidentally mutate the wrong environment.
Per-environment safety. Pair prod with COALESCE_MCP_READ_ONLY=true to hide every write tool on that server while leaving dev fully writable.
No per-call profile juggling. Each server is pinned at startup.
Skip this pattern if you only use one environment - a single registration is simpler. For 2–3 environments it's worth the extra config; beyond that, each server is a separate Node process, so consider whether you actually need them all loaded at once.
Safety model
Three layers prevent destructive surprises. See docs/safety-model.md for the full breakdown (tool annotations, read-only mode, explicit confirmation, COA preflight validation).
Tool annotations - every tool carries MCP readOnlyHint / destructiveHint / idempotentHint. The ⚠️ marker in Tools marks destructiveHint: true tools.
COALESCE_MCP_READ_ONLY=true hides all write/mutation tools at server startup. Use it for audits, agent sandboxes, or pairing with a prod profile.
Explicit confirmation on destructive ops - delete_*, propagate_column_change, cancel_run, clear_data_cache, coa_create, coa_run, coa_deploy, coa_refresh all require confirmed: true.
Diagnosing setup - the diagnose_setup probe and /coalesce-setup MCP prompt.
Design notes
SQL override is disallowed. Nodes are built via YAML/config (columns, transforms, join conditions), not raw SQL. Template generation strips overrideSQLToggle, and write helpers reject overrideSQL fields.
Caching. Large responses are auto-cached to disk. Use cache_workspace_nodes and siblings when you want a reusable snapshot. Configure the threshold with COALESCE_MCP_AUTO_CACHE_MAX_BYTES.
Repo-backed tools. Set COALESCE_REPO_PATH (or add repoPath= to your ~/.coa/config profile) to your local Coalesce repo root (containing nodeTypes/, nodes/, packages/), or pass repoPath on individual tool calls. The server does not clone repos or install packages.
COA CLI versioning. The bundled COA CLI is pinned to an exact alpha version - not a floating @next tag. Every release of this MCP ships with a known-good COA build.
COA describe cache. COA describe output is cached under ~/.cache/coalesce-transform-mcp/coa-describe/<coa-version>/ after first access. Cache is version-keyed - upgrading the MCP automatically invalidates stale content.
Just installed Coalesce Transform Mcp? Say to Claude: "remember why I installed Coalesce Transform Mcpand what I want to try" — it'll save into your Vault.
