47 added, 25 removed. Audit B to A.
---
name: clay
description: Agent-callable Clay tools — create, update, and find rows in Clay tables, and navigate workspaces, tables, views, and users. Use when the user mentions Clay or wants to add, update, or look up rows in a Clay table, even if they don't name Clay explicitly.
license: Elastic-2.0
compatibility: Run `npm install --omit=dev` in this directory, then `node cli.js`. The TypeScript source needs Node.js 22.18+; on older Node, run `cli.js` for build-it-yourself / prebuilt / alternative-runtime options.
metadata:
source: https://github.com/zapier/connectors/blob/main/apps/clay/SKILL.md
title: Clay
api-docs: https://developers.clay.com/
zapier-app-key: ClayCLIAPI
---
# Clay
- _Independent, unofficial connector for Clay. Not affiliated with, endorsed by, or sponsored by Clay. "Clay" is a trademark of its owner, used only to identify the service this connector works with._
+ <!-- BEGIN:skill-intro -->
Agent-callable tools for [Clay](https://www.clay.com/), the spreadsheet-style go-to-market data platform. This connector gets structured data **into** Clay tables and reads specific rows back out: create and update rows, find rows by field value, list a view's rows, and navigate the workspace → table → view → record hierarchy so you can resolve the identifiers those writes need. A workspace holds tables, a table holds rows of typed cells, and views define which columns are visible. Authentication is a single long-lived Clay API key.
+ <!-- legal:disclaimer -->
+
+ _Independent, unofficial connector for Clay. Not affiliated with, endorsed by, or sponsored by Clay. "Clay" is a trademark of its owner, used only to identify the service this connector works with._
+ <!-- /legal:disclaimer -->
+ <!-- END:skill-intro -->
+
## When to use this
+ <!-- BEGIN:skill-use-cases -->
+
- **Write to a Clay table** — add a new row (`createRecord`) or change cells on an existing one (`updateRecord`), e.g. push a lead or enrichment result into a table.
- **Look a row up** — find rows by matching field values (`findRecord`) or page through a view (`listRecords`), e.g. to get a `recordId` before updating.
- **Resolve ids and schema** — navigate workspaces, tables, views, and members (`listWorkspaces`, `listTables`, `getTable`, `listWorkspaceUsers`, `getCurrentUser`) to discover the `tableId`, `viewId`, field ids, select-option ids, and user ids that writes and filters require.
- **Not for** — building tables/views/columns, running enrichments on demand, or bulk export; those aren't exposed here.
+ <!-- END:skill-use-cases -->
+
## Setup
This is an [agentskills.io](https://agentskills.io) skill.
- **If this connector is already exposed to you as callable tools** (e.g. `mcp__clay__<tool>`), that's a valid path — call them directly. Everything below is only for standalone terminal use when no such tools are loaded.
-
- If the connector has not been installed as a skill yet, install it first with `npx skills zapier/connectors --skill clay` (or your harness's own skill-install mechanism), then continue here.
+ If the connector has not been installed as a skill yet, install it first with `npx skills add zapier/connectors --skill clay` (or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or `zapier-sdk` auth commands, run `npm install --omit=dev` here once. Importing the published package as a dependency in your own project instead? That `npm install` already resolves everything — see [`references/use-as-sdk.md`](references/use-as-sdk.md).
- The connector runs on **Node.js 22.18+** and needs a one-time `npm install` in this directory. `cli.js` is the entry point — list every script with `node cli.js --help`, then learn a script's inputs and connections with `node cli.js run <script> --help`. On older Node, run `node cli.js --help` anyway: it detects your runtime and prints how to run without upgrading (the prebuilt npm package, or another runtime) — don't skip the connector just because Node is old.
+ The connector runs on **Node.js 22.18+**. Pick the reference that matches how you're running it, and load it before doing anything else:
- `cli.js` self-checks readiness before running: if dependencies aren't installed it exits non-zero with the exact install command (it disambiguates a read-only directory from a sandbox-blocked package cache). Run that, then re-run your command.
+ | You have... | Load |
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+ | An MCP-aware client — tools may already be loaded (e.g. `mcp__clay__<tool>`), or you can register a local server yourself (or guide the user to) | [`references/use-as-mcp.md`](references/use-as-mcp.md) |
+ | Terminal / subprocess access (you can run `node`) | [`references/use-as-cli.md`](references/use-as-cli.md) |
+ | Only your own code, importing this package as a dependency | [`references/use-as-sdk.md`](references/use-as-sdk.md) |
+ | No tool access, no terminal, no ability to import this package — you write your own code that calls the Clay API directly (e.g. a code-execution sandbox) | [`references/use-as-recipe.md`](references/use-as-recipe.md) |
## Scripts
+ <!-- BEGIN:skill-connections-note? -->
+
All scripts use the single `clay` connection. Cell and filter values are keyed by field id (`f_…`); discover valid field ids, types, and select-option ids with `getTable`, and user ids with `listWorkspaceUsers`.
+ <!-- END:skill-connections-note -->
+ <!-- BEGIN:skill-scripts-table -->
+
| Script | Script name | Connections | Description |
| ------------------------------- | -------------------- | ----------- | ----------------------------------------------------------------------------- |
| `scripts/createRecord.ts` | `createRecord` | `clay` | Add a new row to a table. May run enrichment columns (consumes Clay credits). |
| `scripts/updateRecord.ts` | `updateRecord` | `clay` | Update cell values on an existing row; only the keys you include change. |
| `scripts/findRecord.ts` | `findRecord` | `clay` | Find rows in a table by matching field values (AND-combined). |
| `scripts/listRecords.ts` | `listRecords` | `clay` | List a page of rows from a table view. |
| `scripts/getTable.ts` | `getTable` | `clay` | Describe a table: fields (id, type, select options) and views. |
| `scripts/listTables.ts` | `listTables` | `clay` | List the tables in a workspace. |
| `scripts/listWorkspaces.ts` | `listWorkspaces` | `clay` | List the workspaces the caller can access. |
| `scripts/listWorkspaceUsers.ts` | `listWorkspaceUsers` | `clay` | List members of a workspace (resolve a user id). |
| `scripts/getCurrentUser.ts` | `getCurrentUser` | `clay` | Return the authenticated caller's user id and email. |
+ <!-- END:skill-scripts-table -->
+
+ <!-- BEGIN:disambiguation-and-refusals? -->
+
## Disambiguation & refusals
- **Before updating a row looked up by name, confirm the match.** `findRecord` / `listRecords` can return several rows that share a value (e.g. two records with the same company or person name). Count exact (case-insensitive) matches on the field you searched: exactly one → act on it, don't over-ask; two or more that tie → stop, list the candidates with a distinguishing field (another cell value or the record id), and ask which one before calling `updateRecord`. Never silently pick the first.
- **Always re-resolve the row with a fresh `findRecord` at update time — never reuse a `recordId` you created or saw earlier in the conversation.** A row you added moments ago may no longer be unique (another row with the same value may have been added since), so a stale id hides the ambiguity. Search by the named value again, then apply the count rule above before writing.
- **Don't fake unsupported operations.** This connector cannot create or delete tables, views, or columns, run an enrichment on demand, or delete rows — there is no tool for those. If asked, say it's unsupported and stop; do not substitute a different tool (e.g. writing a new row in place of deleting one) and report it as done.
- ## Auth
-
- Pass auth as one connection string with `--connection [<resolver>:]<value>`. The value is a selector, not the secret; the `<resolver>:` prefix is optional (a bare value goes to the first resolver that claims it). Each script declares the connections it needs and the resolvers each accepts — always run `node cli.js run <script> --help` to see them rather than relying on this file.
+ <!-- END:disambiguation-and-refusals -->
- Clay authenticates with a single long-lived **API key** (in the Clay app under _Settings → Account → API keys_). It needs no browser consent, which suits an agent.
+ ## Auth
- - **Direct token (recommended for v1):** put the key in an environment variable and pass `--connection env:CLAY_API_KEY`. This is the verified path.
- - **Zapier-managed:** `--connection zapier:<connection-id>` uses Zapier's managed auth, retries, and governance layer to inject the key. This path is not yet verified for Clay — prefer the direct token until it is confirmed.
+ Every shape passes auth as one connection **selector**, not the secret — a `[<resolver>:]<value>` string. Every connector accepts `zapier:<connection-id>` (Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The `<resolver>:` prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims `zapier:`. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.
- The key is the same for every script. Run `node cli.js run <script> --help` to see the connection each script accepts.
+ Checking what's already configured first? Don't dump environment values to do it — `env` or `env | grep <name>` prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (`env | cut -d= -f1 | grep -i <name>`) or test a known name directly (`[ -n "$VAR_NAME" ]`).
- ## Running scripts
+ <!-- BEGIN:skill-auth-notes -->
- After `npm install`, run a script by name with `node cli.js run <script>`, or execute its file directly — both take the same arguments and both accept `--help`. Always run a script's `--help` first to learn its exact input schema and connections, then invoke it:
+ Zapier-managed auth is not yet verified for Clay — prefer the direct token (`env:<ENV_VAR>`) until it is confirmed.
+ <!-- END:skill-auth-notes -->
- ```bash
- # default — via the entry point; self-checks readiness and prints friendly diagnostics
- node cli.js run <script> '<input-json>' --connection [<resolver>:]<value>
- # shorthand — runs the script file directly (same args, same Node 22.18+ need, no readiness check)
- ./scripts/<script>.ts '<input-json>' --connection [<resolver>:]<value>
- ```
+ No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:
- When a harness can't execute scripts directly, fall back to MCP — `node cli.js mcp` serves every script as a tool over stdio. Register it as a local MCP server in your client: the stanza is harness-specific (an `mcpServers` entry in Claude Desktop, Cursor, Claude Code, …) with `command: "node"`, `args: ["cli.js", "mcp"]`, run from this directory. Run `node cli.js mcp --help` for auth options. Add the stanza yourself if you can edit the client's MCP config; otherwise guide the user. If a local server isn't possible, guide the user to use Zapier's remote MCP servers at <https://mcp.zapier.com> instead.
+ | | Load |
+ | ------------------------------------ | ---------------------------------------------------------------------- |
+ | Pass the credential directly | [`references/use-without-zapier.md`](references/use-without-zapier.md) |
+ | Route it through a Zapier connection | [`references/use-with-zapier.md`](references/use-with-zapier.md) |
## Output format
Every script returns a `{ data, meta }` envelope:
- - **`data`** — the script's result (the shape its `outputSchema` declares; run the script's `--help` to see that exact schema).
+ - **`data`** — the script's result (the shape its `outputSchema` declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
- **`meta.outputDataValidation`** — what validating `data` did:
- `{ skipped: false, droppedPaths: null }` — validated, nothing removed.
- `{ skipped: false, droppedPaths: [...], instruction }` — validated, but those paths were stripped from `data`: fields the script returned from the API that the `outputSchema` doesn't declare. If you need them, re-run with output validation skipped.
- `{ skipped: true }` — validation was bypassed; `data` is the raw, unchecked script output.
- **Reading dropped fields / `skipOutputDataValidation`.** To receive the raw, unvalidated result, append `--skipOutputDataValidation` to the script invocation. Input validation is never skipped.
+ **Reading dropped fields / `skipOutputDataValidation`.** To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.
- **Trimming the result / `filterOutputData`.** To shrink a large result down to the fields you need, append `--filterOutputData '<jq>'` — a jq expression that post-processes `data`. The jq runs against `data` only, NOT the `{ data, meta }` envelope, so write it rooted at `data` (run the script's `--help` to see its output schema). The transformed value replaces `data`, `meta` is preserved, and the result is NOT re-validated against the output schema.
+ **Trimming the result / `filterOutputData`.** To shrink a large result down to the fields you need, pass a jq expression that post-processes `data` (again, exact syntax per shape). The jq runs against `data` only, NOT the `{ data, meta }` envelope, so write it rooted at `data` (run the script's `--help` — or your shape's equivalent — to see its output schema). The transformed value replaces `data`, `meta` is preserved, and the result is NOT re-validated against the output schema.
+ <!-- BEGIN:skill-references-table -->
+
## References
Load the matching reference file before working in that area:
| Reference | Load when |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [clay-api-gotchas.md](./references/clay-api-gotchas.md) | A call fails or behaves unexpectedly — the raw `authorization` header (no `Bearer`), the undocumented `api.clay.com/v3` table surface, the user→workspace→table→view id chain, field-id/cell shape, the `/find` filter DSL, limit-only paging, or when writes consume Clay credits. |
| [use-as-recipe.md](./references/use-as-recipe.md) | A harness writing its own code against the Clay API (can't load the tools, run the CLI, or import the package) needs the request/response shapes and critical rules. |
+
+ <!-- END:skill-references-table -->