Clay

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._

Agent-callable tools for Clay, 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.

When to use this

• 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.

Setup

This is an 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.

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.

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.

Scripts

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.

| 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. |

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.

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.

• 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.

The key is the same for every script. Run node cli.js run <script> --help to see the connection each script accepts.

Running scripts

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:

# 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>

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.

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).
• 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.

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.

References

Load the matching reference file before working in that area:

| Reference | Load when |

| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| 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 | 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. |