@damiangilgonzalez/harness 1.3.7

package/skills/make/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: make
+description: "Use when operating Make.com (formerly Integromat) programmatically — driving its REST API v2 or the Make MCP server from code or an agent to create, read, update, activate, run, clone or delete scenarios, connections, hooks and data stores. NOT designing what the flow should do (that is `automation-flows`), NOT choosing between Make, n8n and Zapier by billing model (that is `automation-strategy`), NOT a generic typed REST client (that is `api-connector-builder`), NOT receiving inbound webhooks in your own app (that is `webhooks`)."
+tags: [make, integromat, automation, scenarios, blueprint, mcp, no-code, api, workflows]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# Make (Integromat) — operate scenarios by REST API and MCP
+
+Drive a live Make.com account from code or an agent: create scenarios from a
+blueprint, activate/run/stop/clone/delete them, and manage the connections,
+hooks, data stores, and teams around them. This skill owns the **operate**
+half — the API v2 calls and the MCP wiring. It does **not** design the flow;
+what a scenario *should do* (trigger, routes, mapping, dedup, error handler)
+lives in [`automation-flows`](../automation-flows/SKILL.md), and the
+Make-vs-n8n-vs-Zapier billing call lives in
+[`automation-strategy`](../automation-strategy/SKILL.md). Bring the design
+here, and this skill turns it into API payloads and MCP tool calls.
+
+Reality up top (verify at author time — Make ships fast):
+
+- **REST API v2 is GA.** Base URL is **zoned**: `https://{zone}.make.com/api/v2`.
+- **The Make MCP server is GA and free on every plan** — you only pay the
+  scenario **credits** a run consumes. Cloud MCP has two tool tiers: run tools
+  (all plans) and management tools (paid).
+
+## Connect first — API token vs MCP
+
+Two ways in, chosen by *who is driving*:
+
+- **REST API v2** — deterministic CRUD from your own scripts/CI. Full control
+  of the blueprint. Use for provisioning, bulk edits, activate/stop pipelines.
+- **Make MCP server** — lets an MCP client (Claude, Cursor, ChatGPT) call your
+  scenarios and (on paid plans) manage them as tools, no glue code. Use when an
+  **agent** is the operator.
+
+`.env` (never inline secrets — read from the environment):
+
+```bash
+MAKE_ZONE=eu2.make.com        # your org's zone — eu1|eu2|us1|us2 (+ celonis). WRONG ZONE = AUTH ERROR.
+MAKE_API_TOKEN=xxxxxxxx        # Profile → API/SDK → API token. Scopes are FIXED at creation.
+MAKE_TEAM_ID=123456            # teamId a scenario is created under (integer)
+MAKE_MCP_TOKEN=yyyyyyyy        # separate MCP token, for the token-URL MCP transport
+```
+
+**Auth header (API):** `Authorization: Token {MAKE_API_TOKEN}` — the literal
+word `Token`, a space, then the token. OAuth2 is the alternative for
+multi-user apps. **Scopes are chosen when the token is minted and cannot be
+widened later** — mint with `scenarios:read scenarios:write` (and
+`connections`, `hooks`, `datastores`, `teams` as needed) up front; a
+too-narrow token means re-minting, not patching.
+
+## The scenario model (just enough to build the payload)
+
+A **scenario** = exactly one trigger module, then a chain of action modules,
+optionally split by **routers** into branches. Data flows by **mapping**:
+a downstream field references an upstream output as `{{2.email}}` (module 2's
+`email`). The whole thing serializes to a **blueprint** — the JSON you GET, edit,
+and POST back. That is the entire operate-side model you need here.
+
+Do **not** design the flow in this skill. Trigger choice (webhook vs polling),
+branch logic, idempotency/dedup on a data store, and the error handler
+(Break → Incomplete Executions, etc.) are all `automation-flows`. Take its
+build sheet, then encode it as a blueprint below.
+
+## API v2 surface
+
+| Group | Endpoints (case-sensitive!) | Use |
+|---|---|---|
+| Scenarios | `GET/POST /scenarios`, `GET/PATCH/DELETE /scenarios/{id}`, `.../start`, `.../stop`, `.../run`, `.../clone`, `.../blueprint` | the core |
+| Connections | `GET/POST /connections`, `.../{id}/test` | app auth the modules use |
+| Hooks | `GET/POST /hooks`, `.../{id}/ping`, `.../learn-start` | inbound webhooks/mailhooks |
+| Data stores | `GET/POST /data-stores`, `.../{id}/data` | dedup keys, state |
+| Templates | `GET /templates`, `.../{id}/blueprint` | starting-point blueprints |
+| Teams / Orgs | `GET /teams`, `GET /organizations/{id}` | scoping + rate limit |
+
+Two rules that bite: **endpoints and query keys are case-sensitive**, and every
+call is **zoned** — the same token against the wrong `{zone}` returns an auth
+error, not a 404, which sends people chasing a token problem that does not exist.
+
+**Rate limits are per plan** (req/min): Core 60 · Pro 120 · Teams 240 ·
+Enterprise 1000. Read your own real ceiling rather than guessing:
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/organizations/$ORG_ID" | jq '.organization.license.apiLimit'
+```
+
+## Dynamic lifecycle — the blueprint round-trip
+
+The core technique: **you rarely hand-write a blueprint.** You GET one from a
+template or an existing scenario, mutate the JSON, and POST/PATCH it back **as a
+string**. `blueprint` and `scheduling` are sent as JSON *strings*, not objects.
+
+### 1. Get a starting blueprint
+
+```bash
+# From an existing scenario (or a template: GET /templates/{id}/blueprint)
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$TEMPLATE_ID/blueprint" \
+  | jq '.response.blueprint' > bp.json   # wrapper key: verify .response.blueprint at author time
+```
+
+Mutate `bp.json` with your design — module parameters, the `{{n.field}}`
+mappings, router filters. Keep secrets out; wire credentials via a
+**connection id**, never a literal key in the blueprint.
+
+### 2. Create the scenario (blueprint + scheduling as STRINGS)
+
+```bash
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios" \
+  -d "$(jq -n --argjson team "$MAKE_TEAM_ID" \
+        --arg bp "$(jq -c . bp.json)" \
+        --arg sched '{"type":"on-demand"}' \
+        '{teamId:$team, blueprint:$bp, scheduling:$sched}')"
+# scheduling e.g. {"type":"indefinitely","interval":900} (interval seconds) — verify fields at author time.
+# optional: folderId, basedon (template id)
+```
+
+### 3. Validate
+
+The create call itself is the validator — a malformed blueprint returns a 400
+naming the offending module/field. Fix the JSON and re-POST. There is no
+separate schema-lint endpoint; a clean create *is* the pass.
+
+### 4. Dry-run / test before you schedule
+
+Run it once, watching one execution, while still `on-demand` (inactive):
+
+```bash
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID/run" \
+  -H "Content-Type: application/json" -d '{"responsive":true}'
+# inspect the returned execution/bundle output before trusting the flow
+```
+
+### 5. Activate
+
+```bash
+# switch scheduling off on-demand first (PATCH), then start
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID/start"
+```
+
+### 6. Manage — patch, stop, clone
+
+```bash
+# Update: same round-trip — GET blueprint, mutate, PATCH back as a string
+curl -s -X PATCH -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID" \
+  -d "$(jq -n --arg bp "$(jq -c . bp.json)" '{blueprint:$bp}')"
+
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" ".../scenarios/$ID/stop"
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" ".../scenarios/$ID/clone" \
+  -d '{"teamId": 999, "name": "copy"}'   # clone into another team
+```
+
+### 7. Delete — export first (irreversible)
+
+`DELETE /scenarios/{id}` is permanent; there is no undo and no trash. **Never
+delete a live scenario without exporting its blueprint first.**
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  ".../scenarios/$ID/blueprint" | jq '.response.blueprint' > backup-$ID.json  # export
+curl -s -X DELETE -H "Authorization: Token $MAKE_API_TOKEN" ".../scenarios/$ID"
+```
+
+## Make MCP — run and manage scenarios as tools
+
+The Make MCP server hands an MCP client your scenarios as callable tools. Two
+transports:
+
+- **OAuth (remote):** point the client at `https://mcp.make.com` (or the
+  `/stream`, `/sse` variants). Scopes granted at consent decide which tools appear.
+- **MCP token (per-zone):** `https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless`
+  (also `/stream`, `/sse`). `/stateless` times out at ~60 s; `/stream` and
+  `/sse` allow ~5 min — a long scenario needs `/stream` or `/sse`.
+
+Tool tiers (exact names move — confirm in the client's tool list at author time):
+
+- **Run tools — all plans.** Enumerate on-demand scenarios and execute one with
+  inputs, returning its output. This is what lets an agent *use* your automation.
+- **Management tools — paid plans.** View/modify scenarios, connections, hooks,
+  data stores, teams, organizations — the CRUD above, surfaced as tools.
+
+Client config sketch (token transport):
+
+```json
+{ "mcpServers": { "make": {
+  "url": "https://eu2.make.com/mcp/u/${MAKE_MCP_TOKEN}/stream"
+} } }
+```
+
+MCP calls consume the scenario's normal **credits** — the server is free, the
+runs are not. **Legacy note:** the local stdio server `integromat/make-mcp-server`
+predates the cloud one and exposes on-demand scenarios as tools over stdio;
+prefer the cloud server unless you specifically need a local process.
+
+## Honesty / gotchas
+
+- **Zone trap.** Wrong `{zone}` → auth error with a perfectly valid token. Check
+  the zone before you suspect the token.
+- **Case-sensitive paths.** `/scenarios` works, `/Scenarios` does not.
+- **`blueprint` and `scheduling` are strings, not objects** — stringify them or
+  the create/update fails.
+- **Token scopes are frozen at creation.** Can't widen later; re-mint instead.
+- **Delete is irreversible** — export the blueprint first, always.
+- **Credits, not operations.** Make's billing unit became **credits** (was
+  "operations"); API-triggered and MCP-triggered runs both burn them.
+- **`.run` on an inactive scenario** is your dry run; scheduled execution needs
+  `.start` — don't confuse the two.
+- **Don't hand-author blueprints from scratch** — round-trip a template; the
+  format is large and undocumented in full.
+
+## Related skills
+
+- [`automation-flows`](../automation-flows/SKILL.md) — **design** the flow
+  (trigger, routes, mapping, dedup, error path). Build it there, encode the
+  blueprint here. Design ↔ operate is the boundary.
+- [`automation-strategy`](../automation-strategy/SKILL.md) — choose Make vs n8n
+  vs Zapier by billing model *before* committing to this skill.
+- [`webhooks`](../webhooks/SKILL.md) — building the inbound endpoint that
+  *receives* events in your own app (vs Make's `hooks` API here).
+- [`api-connector-builder`](../api-connector-builder/SKILL.md) — a generic typed
+  REST client with auth/pagination/backoff, when you outgrow curl.
+- Other platforms: `n8n`, `zapier`, `power-automate` (their own skills).
+
+## Checklist
+
+- [ ] `MAKE_ZONE` matches the org's actual zone (ruled out the zone trap).
+- [ ] API token minted with all scopes needed (scenarios + connections/hooks/
+      datastores as required) — scopes can't be widened later.
+- [ ] Blueprint obtained by round-trip (template/existing), not hand-written.
+- [ ] `blueprint` and `scheduling` sent as JSON **strings**; `teamId` set.
+- [ ] Credentials referenced by connection id — no secrets in the blueprint.
+- [ ] Dry-ran with `/run` and inspected output before `/start`.
+- [ ] Blueprint exported to a file before any `DELETE`.
+- [ ] For MCP: right transport for run length (`/stream`|`/sse` if >60 s), and
+      manager tools confirmed present only if the plan is paid.
+
+## References
+
+- `references/api-v2-cheatsheet.md` — endpoints, auth, scopes, rate limits, the
+  common response envelope, and error codes.
+- `references/blueprint-round-trip.md` — the GET→mutate→POST recipe in depth,
+  blueprint anatomy, and the stringify gotcha.
+- `references/make-mcp-and-auth.md` — MCP transports, tool tiers, client configs,
+  and the token-vs-OAuth decision.

package/skills/make/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — make
+
+`cases.yaml` holds three groups scored by an LLM judge against the rendered
+skill. `should_trigger` confirms Make owns programmatic/MCP operation of a
+Make.com account (create/run/clone/activate/delete scenarios, the blueprint
+round-trip, the zone trap). `should_not_trigger` confirms clean deferral to the
+real siblings — `automation-flows` for flow design, `automation-strategy` for
+platform choice, `n8n` for that platform, `api-connector-builder` for generic
+clients, `webhooks` for inbound receivers. The `capability` case checks the body
+carries the load-bearing facts: the zoned/case-sensitive API, the
+string-not-object blueprint/scheduling, the round-trip, run-before-start,
+export-before-delete irreversibility, frozen token scopes, and the Make MCP
+tiers. Run via the repo's eval runner; treat a miss as a cue to sharpen the
+description's triggers/boundary or fill a body gap.

package/skills/make/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: make
+
+should_trigger:
+  - prompt: "Create a Make.com scenario from a blueprint via the API and activate it from my deploy script."
+    why: Core operate task — POST /scenarios with a blueprint string, then /start.
+  - prompt: "Export a Make scenario blueprint, change the Notion module's mapping, and push it back."
+    why: The blueprint round-trip (GET /blueprint → mutate → PATCH as a string) this skill owns.
+  - prompt: "My Make API token keeps returning an auth error even though it's valid and the scopes look right."
+    why: Classic zone trap — wrong {zone} in the base URL, not a token problem.
+  - prompt: "Connect the Make MCP server so Claude can run my scenarios as tools."
+    why: MCP transport + tool-tier setup; the agent-operator path.
+  - prompt: "Clone this Integromat scenario into another team and stop the original from a cron job."
+    why: /clone and /stop lifecycle endpoints driven programmatically.
+  - prompt: "Automatiza la creación de escenarios en Make.com desde la API, incluyendo teamId y scheduling."
+    why: Spanish phrasing of programmatic scenario creation; required teamId + scheduling string.
+  - prompt: "Read my Make org's real API rate limit before I bulk-update 200 scenarios."
+    why: GET /organizations/{id} → license.apiLimit, plus rate-limit awareness for API operation.
+
+should_not_trigger:
+  - prompt: "Design a Make scenario that dedupes Stripe webhooks and has a proper error path before an external call."
+    route_to: automation-flows
+    why: Flow design (trigger, dedup, error handler) — build it there, then encode the blueprint here.
+  - prompt: "Should I use Make, n8n, or Zapier for 80k runs a month given the billing models?"
+    route_to: automation-strategy
+    why: Platform choice by cost model, not operating a Make account.
+  - prompt: "Create and activate an n8n workflow via its REST API."
+    route_to: n8n
+    why: Different platform; n8n has its own operate skill.
+  - prompt: "Build a typed TypeScript client for a REST API with OAuth refresh, pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: Generic API-client engineering, not Make-specific operation.
+  - prompt: "Verify the HMAC signature on inbound webhooks arriving at my Express endpoint and queue them."
+    route_to: webhooks
+    why: Inbound receiver in the user's own app, not Make's hooks API.
+
+capability:
+  - scenario: "Programmatically create a Make scenario from a template blueprint, dry-run it, activate it, and later delete it safely — plus offer the Make MCP path for an agent operator."
+    must_include:
+      - "Zoned base URL https://{zone}.make.com/api/v2 with header Authorization: Token {token}, and the zone trap (wrong zone → auth error with a valid token)."
+      - "POST /scenarios requires teamId, plus blueprint and scheduling sent as JSON STRINGS (not objects)."
+      - "Blueprint round-trip: GET /scenarios/{id}/blueprint (or a template), mutate the JSON, send back as a string on create/PATCH."
+      - "Dry-run with POST /scenarios/{id}/run and inspect output before POST /scenarios/{id}/start to activate."
+      - "Irreversibility rule: export the blueprint to a file before DELETE /scenarios/{id} — deletion is permanent."
+      - "Token scopes are fixed at creation and cannot be widened later; endpoints are case-sensitive."
+      - "Make MCP server (GA, free; runs cost credits) via OAuth https://mcp.make.com or token URL https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless|stream|sse, with run tools (all plans) vs management tools (paid)."

package/skills/make/references/api-v2-cheatsheet.md

@@ -0,0 +1,114 @@
+# Make API v2 — cheat-sheet
+
+Current as of July 2026. Endpoints and query keys are **case-sensitive** and
+every call is **zoned**. Verify anything you depend on at
+[developers.make.com](https://developers.make.com/api-documentation) at author time.
+
+## Base URL & auth
+
+```
+https://{zone}.make.com/api/v2
+```
+
+- `{zone}` ∈ `eu1 | eu2 | us1 | us2` (plus `celonis` for that deployment). The
+  wrong zone returns an **authentication error** even with a valid token — this
+  is the single most common Make API mistake.
+- Header: `Authorization: Token {MAKE_API_TOKEN}` — literal `Token`, a space,
+  the token. OAuth2 exists for multi-user apps.
+- Content type for writes: `Content-Type: application/json`.
+
+## Token scopes (frozen at creation)
+
+Mint the token in **Profile → API/SDK**. You pick scopes **once**; they cannot
+be widened afterward — a too-narrow token means minting a new one. Grant only
+what you use, e.g. `scenarios:read scenarios:write connections:read
+connections:write hooks:read hooks:write datastores:read datastores:write
+teams:read organizations:read`.
+
+## Response envelope
+
+Most responses wrap the payload under a root key named for the resource, e.g.
+`{ "scenario": {...} }`, `{ "scenarios": [...] }`, `{ "response": { "blueprint": {...} } }`.
+Extract with `jq '.scenario'` etc. **Confirm the exact wrapper per endpoint at
+author time** — a few endpoints differ.
+
+## Endpoint map
+
+### Scenarios (the core)
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/scenarios?teamId={id}` | list; paginate with `pg[limit]` / `pg[offset]` |
+| POST | `/scenarios` | body: `teamId` (int), `blueprint` (**string**), `scheduling` (**string**); optional `folderId`, `basedon` |
+| GET | `/scenarios/{id}` | metadata (not the blueprint) |
+| PATCH | `/scenarios/{id}` | update — send `blueprint`/`scheduling`/`name` as strings |
+| DELETE | `/scenarios/{id}` | **permanent, no trash** — export blueprint first |
+| GET | `/scenarios/{id}/blueprint` | the editable JSON (round-trip source) |
+| POST | `/scenarios/{id}/start` | activate scheduled execution |
+| POST | `/scenarios/{id}/stop` | deactivate |
+| POST | `/scenarios/{id}/run` | one manual run; `{"responsive":true}` waits for result |
+| POST | `/scenarios/{id}/clone` | body `{teamId, name}` — copy into a team |
+
+### Connections
+
+`GET/POST /connections`, `GET/DELETE /connections/{id}`,
+`POST /connections/{id}/test`. Modules reference a connection **by id** for app
+auth — the blueprint holds the id, never the secret.
+
+### Hooks (Make's inbound webhooks/mailhooks)
+
+`GET/POST /hooks`, `GET/DELETE /hooks/{id}`, `POST /hooks/{id}/ping`,
+`POST /hooks/{id}/learn-start` / `learn-stop` (structure learning). This is
+Make's *own* webhook receiver; building an inbound endpoint in **your** app is
+the `webhooks` skill.
+
+### Data stores
+
+`GET/POST /data-stores`, `GET/DELETE /data-stores/{id}`,
+`GET/POST/DELETE /data-stores/{id}/data`. The idiomatic place for dedup keys and
+cross-run state (see `automation-flows` for the dedup pattern).
+
+### Templates
+
+`GET /templates`, `GET /templates/{id}/blueprint`. A published template's
+blueprint is the cleanest round-trip starting point.
+
+### Teams & organizations
+
+`GET /teams?organizationId={id}`, `GET /organizations/{id}`. Read your real
+rate ceiling: `GET /organizations/{id}` → `license.apiLimit`.
+
+## Rate limits (req/min, per plan)
+
+| Plan | Limit |
+|---|---|
+| Core | 60 |
+| Pro | 120 |
+| Teams | 240 |
+| Enterprise | 1000 |
+
+Don't hard-code it — read `license.apiLimit` from your own org. On `429`, back
+off and retry (generic retry/backoff engineering: `api-connector-builder`).
+
+## Scheduling string
+
+`scheduling` is a JSON **string**. Common shapes (verify fields at author time):
+
+```json
+{"type":"on-demand"}
+{"type":"indefinitely","interval":900}   // interval in seconds
+```
+
+`on-demand` scenarios run only via `/run` or a webhook trigger; `indefinitely`
+runs on the interval once `/start`ed.
+
+## Errors you will actually hit
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Auth error with a valid token | wrong `{zone}` | match the org's zone |
+| 400 on create | `blueprint`/`scheduling` sent as objects | stringify them |
+| 400 naming a module/field | malformed blueprint | fix that node, re-POST |
+| 403 on a valid endpoint | token missing that scope | re-mint with the scope |
+| 404 on a path that should exist | wrong case in the path | fix casing |
+| 429 | over plan rate limit | back off; read `apiLimit` |

package/skills/make/references/blueprint-round-trip.md

@@ -0,0 +1,128 @@
+# The blueprint round-trip
+
+You almost never author a Make blueprint by hand. You **export** one, **mutate**
+the JSON, and **send it back as a string**. This file is that recipe in depth.
+
+## Why round-trip
+
+A blueprint is a large, only-partially-documented JSON structure. Writing one
+from scratch means guessing internal module parameter keys and metadata that the
+create endpoint will reject. Exporting a working scenario (or a published
+template) gives you a guaranteed-valid skeleton to edit — the diff you make is
+small and reviewable.
+
+## Blueprint anatomy (top level)
+
+```jsonc
+{
+  "name": "My scenario",
+  "flow": [                     // ordered modules — index 1, 2, 3…
+    {
+      "id": 1,
+      "module": "gateway:CustomWebHook",   // module type
+      "version": 1,
+      "parameters": { "hook": 123456 },    // references a hook by id
+      "mapper": {},                        // inbound mapping for this module
+      "metadata": { "designer": { "x": 0, "y": 0 } }
+    },
+    {
+      "id": 2,
+      "module": "notion:createDatabaseItem",
+      "version": 2,
+      "parameters": { "__IMTCONN__": 78910 }, // connection id — NOT a secret
+      "mapper": { "title": "{{1.body.name}}" } // maps module 1's output
+    }
+  ],
+  "metadata": {
+    "instant": true,
+    "scenario": { "roundtrips": 1, "maxErrors": 3, "autoCommit": true },
+    "designer": { "orphans": [] }
+  }
+}
+```
+
+Key ideas:
+
+- **`flow`** is the ordered module list. Each module has an integer `id`; a
+  trigger sits at index 1.
+- **Mapping** is `{{sourceId.path}}` — `{{1.body.name}}` = module 1's
+  `body.name`. This is the same mapping `automation-flows` designs; here you are
+  only serializing it.
+- **Connections and hooks are referenced by id** (`__IMTCONN__`, `parameters.hook`).
+  Create the connection/hook first (or reuse one), put its id here. Never inline
+  an API key or token.
+- **Routers/branches** appear as nested `routes` arrays inside a router module.
+- `metadata.scenario` carries run settings (max errors, sequential processing,
+  auto-commit) — design decisions from `automation-flows`, encoded here.
+
+## Step 1 — export
+
+```bash
+curl -s -H "Authorization: Token $MAKE_API_TOKEN" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$SRC_ID/blueprint" \
+  | jq '.response.blueprint' > bp.json     # verify the .response.blueprint wrapper at author time
+```
+
+Or from a template: `GET /templates/{id}/blueprint`.
+
+## Step 2 — mutate
+
+Edit `bp.json`: rename it, repoint `parameters.__IMTCONN__` /
+`parameters.hook` at *your* connection/hook ids, adjust `mapper` expressions,
+add/remove modules in `flow`. If you add a module, give it a fresh integer `id`
+and wire downstream mappers to it.
+
+Validate it is still JSON before sending:
+
+```bash
+jq empty bp.json && echo "valid json"
+```
+
+## Step 3 — send back as a STRING
+
+The create/update endpoints want `blueprint` (and `scheduling`) as JSON
+**strings**, not objects. Build the body with `jq` so the stringify is correct:
+
+```bash
+# CREATE
+curl -s -X POST -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios" \
+  -d "$(jq -n \
+        --argjson team "$MAKE_TEAM_ID" \
+        --arg bp "$(jq -c . bp.json)" \
+        --arg sched '{"type":"on-demand"}' \
+        '{teamId:$team, blueprint:$bp, scheduling:$sched}')"
+
+# UPDATE (same scenario)
+curl -s -X PATCH -H "Authorization: Token $MAKE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://$MAKE_ZONE/api/v2/scenarios/$ID" \
+  -d "$(jq -n --arg bp "$(jq -c . bp.json)" '{blueprint:$bp}')"
+```
+
+`jq -c . bp.json` compacts the blueprint to one line; passing it via `--arg`
+makes it a **string** field. `--argjson team` keeps `teamId` a number.
+
+## The stringify gotcha
+
+The most common failure is sending `blueprint` as a nested object:
+
+```jsonc
+// WRONG — object, 400
+{ "teamId": 123, "blueprint": { "flow": [ ... ] }, "scheduling": {"type":"on-demand"} }
+
+// RIGHT — string
+{ "teamId": 123, "blueprint": "{\"flow\":[...]}", "scheduling": "{\"type\":\"on-demand\"}" }
+```
+
+If you build the request in Python/JS, `json.dumps()` / `JSON.stringify()` the
+blueprint value itself and assign the resulting string.
+
+## Verify, then activate
+
+The create/PATCH call is the validator — a bad blueprint returns a 400 naming
+the offending module. On success, dry-run with `POST /scenarios/{id}/run`
+(`{"responsive":true}` to get the output inline), inspect the bundle, then
+`POST /scenarios/{id}/start`. Before any `DELETE`, re-export the blueprint to a
+file — deletion is permanent.

package/skills/make/references/make-mcp-and-auth.md

@@ -0,0 +1,101 @@
+# Make MCP server & auth setup
+
+The Make MCP server exposes your Make account to an MCP client (Claude, Cursor,
+ChatGPT, or any MCP-capable agent) so it can run — and, on paid plans, manage —
+scenarios as tools. It is **GA and free on every plan**; you pay only the normal
+scenario **credits** each run consumes. Verify specifics at
+[developers.make.com/mcp-server](https://developers.make.com/mcp-server) at
+author time — tool names and transports move.
+
+## Transports
+
+Two ways to authenticate the connection:
+
+### OAuth (remote, recommended for end users)
+
+Point the client at the hosted endpoint:
+
+```
+https://mcp.make.com            # stateless (default)
+https://mcp.make.com/stream     # streamable HTTP
+https://mcp.make.com/sse        # server-sent events
+```
+
+The client runs an OAuth consent flow; the **scopes you grant at consent decide
+which tools appear**. No token to manage by hand.
+
+### MCP token (per-zone URL)
+
+Generate an **MCP token** in Make (Profile → API/SDK) and embed it in a zoned URL:
+
+```
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stream
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/sse
+```
+
+- `{zone}` is your org's zone (`eu1|eu2|us1|us2`, + `celonis`) — same **zone
+  trap** as the REST API: wrong zone = auth failure.
+- The MCP token is **separate** from the REST API token.
+
+### Timeout — pick the transport by run length
+
+| Transport | Timeout | Use for |
+|---|---|---|
+| `/stateless` | ~60 s | quick scenarios, simple clients |
+| `/stream` | ~5 min 20 s | long-running scenarios |
+| `/sse` | ~5 min 20 s | streaming clients |
+
+A scenario that takes longer than 60 s on `/stateless` will time out — use
+`/stream` or `/sse`.
+
+## Tool tiers
+
+Exact tool names change; confirm in the client's tool list. The **tiers** are
+stable:
+
+- **Run tools — all plans.** List the account's on-demand scenarios and execute
+  a chosen one with inputs, returning its output bundle. This is what lets an
+  agent *use* an automation you built.
+- **Management tools — paid plans only.** View and modify scenarios,
+  connections, hooks, data stores, teams, and organizations — effectively the
+  REST CRUD surfaced as MCP tools. On a free plan these do not appear.
+
+On the OAuth transport, missing scopes (not just plan tier) can also hide tools.
+
+## Client config sketches
+
+Token transport (generic `mcpServers` block; adapt to your client):
+
+```json
+{
+  "mcpServers": {
+    "make": {
+      "url": "https://eu2.make.com/mcp/u/${MAKE_MCP_TOKEN}/stream"
+    }
+  }
+}
+```
+
+For stdio-only clients, bridge a streamable-HTTP URL to stdio with a proxy such
+as `mcp-proxy`.
+
+## Legacy local server
+
+`integromat/make-mcp-server` is the **older local stdio** server. It runs as a
+local process and exposes your on-demand scenarios as tools over stdio. It
+predates the cloud server; prefer the cloud MCP unless you specifically need a
+local, offline-ish process (e.g. an air-gapped client that cannot reach
+`mcp.make.com`).
+
+## Credits, not a free lunch
+
+The MCP *server* is free, but every scenario an MCP call runs burns the same
+**credits** as any other run. An agent that loops over a run tool can quietly
+drain credits — cap it the way you would any autonomous consumer.
+
+## When NOT to use MCP
+
+If the operator is your own deterministic script/CI, the REST API v2 is simpler
+and fully controllable — MCP earns its keep only when an **agent** is the one
+driving Make.