---
name: zapier-build
description: >
  Build or extend Zapier connectors, integrations, MCP workflows, and SDK
  clients using the local Mongo reference. Use when the user mentions Zapier,
  zapier-platform, zapier-sdk, MCP tools, a new Zapier app/connector, triggers,
  actions, OAuth for Zapier, or runs /zapier-build.
---

# Zapier build

Always start here — do not invent CLI names, `selected_api` ids, or action keys.

```js
db.platform_reference.findOne({ kind: "guide", key: "build-new-connector" })
```

Same file on disk: `PLATFORM-REFERENCE.md`.

## Route

| Intent | Next |
|--------|------|
| Hosted MCP / AI client | `guide/zapier-mcp` then `kind: "mcp_function"` · `MCP-REFERENCE.md` |
| Any function (CLI / `z.*` / SDK) | `guide/zapier-functions` · `FUNCTIONS-REFERENCE.md` |
| Publish a directory integration | `cli_function` + `core_function` + `schema_json` + `template` |
| Call existing apps from code | `sdk_function` (camelCase twins on `zapier.*`) |
| Public REST | `api_function` |
| Schema / changelog | `schema_json`, `schema_type`, `platform_news` |

## Local tools

- PATH: `$HOME/.npm-global/bin` (`zapier-platform` 19.1.0, `zapier-sdk` 0.77.1)
- Mongo: `./scripts/mongo-tunnel.sh` then `source ~/.mcp-env`
- Golden app: `scratch/oauth2-typescript` (already `validate`s after `zapier-platform build`)
- Example sources: `repos/zapier-platform/example-apps/*` and `kind: "template"`

## Build a new integration

1. Prefer copying `scratch/oauth2-typescript` or `zapier-platform init DIR --template <auth> --language typescript`.
2. Implement `(z, bundle)` with `z.request` only. Throw `z.errors.RefreshAuthError` on refreshable 401.
3. `zapier-platform validate` then `invoke` / `test`. Triggers/searches return arrays; creates return one object.
4. `register` + `push` only after the user is logged in (`~/.zapierrc`). Do not invent a deploy key.

## MCP

Discover → enable → inspect (repeat for dropdowns) → execute. Writes need explicit user approval. Successful executes cost 2 tasks.

## Do not

- Mix `zapier-platform` (publish) with `zapier-sdk` (consume).
- Recommend AI Actions / NLA.
- Hardcode app or action keys; discover via MCP or `zapier-sdk list-apps`.