AGENT SKILL

coalesce-transform-mcp-install

Use when installing, connecting, or troubleshooting the hosted Coalesce Transform MCP server in an MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Cortex Code) — endpoint URL, access token handling, registration, and verification. Not for coa CLI auth (use coalesce-cloud-api).

License 许可
MIT
最近更新
2026-11-11
Stars
★ 0
Forks
0

01 前言 Front Matter

name
coalesce-transform-mcp-install
description
Use when installing, connecting, or troubleshooting the hosted Coalesce Transform MCP server in an MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Cortex Code) — endpoint URL, access token handling, registration, and verification. Not for coa CLI auth (use coalesce-cloud-api).

03 SKILL.md 正文

<!-- coalesce-node-managed: true -->

Install the Coalesce Transform MCP

Scope: registering the hosted Coalesce Transform MCP server (HTTP transport) in an MCP client so agents can query Coalesce projects, environments, and runs. This is client configuration only — it does not touch the workspace repo or the warehouse. For coa CLI credentials and ~/.coa/config, use coalesce-cloud-api instead.

Source of truth: MCP quickstart and the per-client guides linked below. If this skill and the docs disagree, the docs win.

What you need

  • Endpoint — https://<app-host>/api/v1/mcp, where <app-host> is the host the user signs into (e.g. app.coalescesoftware.io, or a custom subdomain like mycompany.app.eu.coalescesoftware.io). Tenancy is resolved from the token, but use the sign-in host so errors are obvious.
  • Access token — generated in the Coalesce App: Deploy tab → Generate Access Token. This is a browser step; you cannot do it. Ask the user to generate one and provide it (or export it as an env var — preferred, see below). It is the same token coa and the REST API use, so a user with a working ~/.coa/config already has one; with their permission you may reuse the token value from that file rather than asking them to generate another.

Token handling — read before running anything

  • NEVER echo, print, or repeat the token back in conversation or logs.
  • NEVER write a literal token into a file that is committed (.mcp.json at repo root is usually committed — use env-var interpolation there).
  • Prefer an environment variable end to end: have the user export COALESCE_ACCESS_TOKEN=... themselves, then reference $COALESCE_ACCESS_TOKEN / ${COALESCE_ACCESS_TOKEN} in commands and config so the secret never appears in shell history or the transcript.
  • Registering an MCP server stores the token in client config (e.g. ~/.claude.json). That is expected, but say so, and ASK FIRST before writing any config file.

Claude Code

Preferred — user scope, token via env var (single quotes so the shell does not expand it into history; Claude Code expands ${...} at connect time):

claude mcp add --transport http --scope user coalesce-transform \
  "https://<app-host>/api/v1/mcp" \
  --header 'Authorization: Bearer ${COALESCE_ACCESS_TOKEN}'

Or project-shared: commit a .mcp.json at the repo root with env-var interpolation, NEVER a literal token:

{
  "mcpServers": {
    "coalesce-transform": {
      "type": "http",
      "url": "https://<app-host>/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${COALESCE_ACCESS_TOKEN}"
      }
    }
  }
}

A server added mid-session is NOT available until the session reconnects. Tell the user to run /mcp (or restart the session) before verifying — do not report failure just because the tools are not visible yet. And ${...} is expanded from the environment Claude Code was LAUNCHED from: if the user exported the token after starting the session, /mcp alone will not pick it up — they must restart claude from a shell that has the variable set (e.g. after adding the export to their shell profile).

Other clients

Same endpoint and header; follow the client guide for where config lives:

Verify

After reconnect/restart, ask: "List Coalesce projects in this organization." Success returns the org's Projects. On an auth error, re-check the token (regenerate if in doubt) and confirm the URL host matches where the user signs in. Available tools: MCP tool reference.

Approval gates

  • Without asking: reading docs, composing the command/config for review, and the post-install verification query (read-only cloud call).
  • ASK FIRST: writing or editing any client config (claude mcp add, .mcp.json, claude_desktop_config.json, …), reading a token out of ~/.coa/config, and committing .mcp.json to the repo.
  • NEVER: generate/scrape tokens from the browser yourself, place a literal token in a committed file, or paste a token into chat output.

04 同仓库更多 Skills

Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-sql-transformation

Use when editing the SQL inside existing Coalesce V2 node files (.sql) — changing column expressions, joins, filters, CTEs, inline column annotations, or ref() macros. Not for creating/deleting node files (use coalesce-pipeline-structure).

★ 0
Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-review-risk

Use when reviewing Coalesce pipeline changes for correctness, impact, and risk before approval — READ-ONLY analysis of diffs, coa validate/dry-run evidence, and downstream blast radius. Never edits files or runs warehouse-mutating commands.

★ 0
Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-rename-node-cascade

Rename a Coalesce node and cascade the new name through every downstream ref(), job selector, and subgraph selector, with quote-agnostic matching and validation.

★ 0
Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-quality-test-authoring

Decide which data quality tests a table, view or model needs, and write them in whatever test format the project already uses (dbt, SYNQ YAML, SQLMesh audits, Soda, Great Expectations, custom SQL, and so on). Use it when asked to add, suggest, review or extend data tests for a warehouse asset, or when a change to a model should come with tests.

★ 0
Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-pipelines

Use when working in a Coalesce Transform repository (data.yml + nodes/ with <LOCATION>-<NAME>.sql/.yml files) — building, editing, validating, or running data transformation pipelines with the coa CLI, including editing V1 .yml nodes and shared config (data.yml, locations, environments, jobs, node types). Start here; it routes to the more specific coalesce-* skills.

★ 0
Coalesce-Software-Inc
Coalesce-Software-Inc/coalesce-platform-skills

coalesce-pipeline-structure

Use when creating, deleting, renaming, or rewiring Coalesce nodes, subgraphs, or jobs — changing the structural topology of the transformation DAG. Not for editing SQL inside an existing node (use coalesce-sql-transformation).

★ 0