Tentt

Clay API and MCP: what Clay exposes and how to drive it from Claude Code

By David Walker-Dobson, GTM engineer ยท Updated

Clay API and MCP: what Clay exposes and how to drive it from Claude Code

The Clay API is several separate things. Inbound webhooks push rows into a table, the HTTP API column calls other APIs from a table, and the newer Public API and CLI run Clay functions from code. Clay also offers an MCP connector for Claude. As of October 2026, webhooks and the HTTP API column need the Growth plan.

Key takeaways

  • Clay has no single REST API: as of October 2026 it offers inbound webhooks, an HTTP API column, a Public API at api.clay.com/public/v0, a CLI and plugin, and MCP.
  • Inbound webhook sources are capped at 50,000 submissions that deleting rows does not reset; only Enterprise auto-delete (passthrough tables) lifts the cap.
  • Clay's pricing page lists webhooks and the HTTP API on Growth (from $495 a month billed monthly, $446 annually) and Enterprise, while Clay's developer platform is stated to be on all plans.
  • The official MCP route is built for reps and agents running Clay Functions, with per-user credit limits that reset on the 1st of each month. Clay documents no way for it to write rows into a table.
  • Anything installed from an npm package or MCP directory with Clay in its name needs its publisher checking, because other products share the name.

What does the Clay API actually include?

Clay does not have one API. It has five separate entry points, built at different times, with different plan requirements and different jobs. Teams searching for the Clay API are usually looking for one of them, and mixing them up is the most common reason a build stalls. The table below lists each one as of October 2026.

Entry pointDirectionWhat it doesOfficial?
Inbound webhook sourceInto ClayA table gets a unique URL; you POST JSON and each submission becomes a rowYes
HTTP API columnOut of ClayCalls any API (GET, POST, PUT, DELETE) from a table row, or imports a list from an API as a sourceYes
Public API (api.clay.com/public/v0)Code to ClayRuns functions, searches Clay's database, reads results; webhooks notify you when a run finishesYes
CLI and agent pluginAgent to ClayThe clay command plus skills for Claude Code, Codex and CursorYes
MCPAssistant to ClayLets Claude, ChatGPT and others find, enrich and run FunctionsYes (hosted connector); npm packages vary

The split matters because Clay's Public API documents no endpoint for writing rows into a table. Its tables endpoint is a structured read query, available on Enterprise only and capped at 100 records a request. So to push rows in from code or another tool as they happen, the inbound webhook is still the route. See the Clay integrations guide for native provider connections.

How do Clay webhooks work, and what are the limits?

A Clay webhook source is the simplest way to push leads in. In a workbook you click + Add, search for Webhooks, choose Monitor webhook and copy the URL or the cURL command. Clay's docs say the endpoint receives data through HTTP POST requests in JSON format, and you can optionally add an authentication token to the request header. Clay shows the token once, so copy it straight away.

The limits are the part that catches teams out. Clay's documentation says webhook sources are limited to 50,000 submissions and that the limit persists even after deleting rows. On Enterprise you can enable auto-delete, also called passthrough tables, so one webhook accepts unlimited submissions. On every other plan you create a new webhook when you hit 50,000. Community answers from Clay staff also mention a per-workspace processing rate of about 10 records a second with a burst of 20 and a 100KB payload cap, but those figures come from forum replies, not the docs, so test them before relying on them.

Note that Clay also uses the word webhook for something different. In the Public API, a webhook is an outbound notification: Clay sends a signed POST to your URL when a function run has finished, so you do not have to poll. The payload carries a webhook id, a timestamp and the run id, and the signature arrives in an X-Clay-Signature header as sha256= followed by an HMAC-SHA256 hex digest of the raw body. Clay says delivery is not guaranteed, so keep polling the run as a fallback.

What can the Clay HTTP API column do?

The HTTP API integration connects a table to any tool with an endpoint, even when Clay has no native integration. Clay's overview describes two modes. As an enrichment it adds API data to existing rows, one row at a time. As a source it imports a list from an API into a new table, with pagination up to 50,000 rows.

Manual setup covers the HTTP method, the endpoint URL, query parameters, a JSON body, headers, the path to the response field you want, a rate limit and an option to remove empty fields. You can save authentication headers once as a workspace account and reuse them across columns. For a source, you also set the path to the results array and, optionally, retries, a response timeout in milliseconds and a static IP.

Clay's guidance is to test on a single row before running the full table, and to use conditional runs so the column only fires when an earlier field is filled. That matters for cost: Clay meters platform work as Actions, separately from data credits, and the Clay pricing guide shows how both are metered. Clay's pricing page lists the HTTP API under Growth and Enterprise, with no HTTP API on Free or Launch.

What are Clay's Public API, CLI and plugin?

The Public API is Clay's newer, code-first route. Clay's docs show a base URL of https://api.clay.com/public/v0, authentication with a clay-api-key header, and a pattern of starting an asynchronous run and then fetching its results. A function run is a POST to /routines/{routine_id}/run with a list of items, each with an id and an inputs object. Results come from a GET on the run, which returns HTTP 202 with progress counters while it works and HTTP 200 with status complete when it is done. A completed run can still contain failed items, so check each item.

To get a key, create one in the Clay app under API and CLI, then API keys, or run clay api-keys create --name "<key name>" from the CLI, which shows the key once. Keys are tied to the user who made them and that user's workspace access, so a key stops working if that person leaves; use a dedicated service user. Store the key in an environment variable such as CLAY_PUBLIC_API_KEY, keep it server-side and send it in the clay-api-key header.

For volume, Clay documents a batch route: request an upload URL, upload a JSONL file with one item per line, start the run with the returned file id, then fetch results. The rate limit is per workspace and Clay publishes no numbers: you get HTTP 429 with a Retry-After header, and Clay says to use exponential backoff with jitter.

The CLI and plugin are the same surface wrapped for agents. Clay's quickstart tells you to ask your coding agent to set up the plugin from Clay's agent-plugins repository on GitHub; the setup puts clay on your PATH and signs you in through the browser. The CLI prints JSON to stdout and uses exit codes: 3 for authentication, 4 for rate limiting, 6 for not found. Clay's API and CLI page says the developer platform is available on all plans, including Free and trial, runs on Mac and Linux (Windows through WSL), and consumes the same credits and Actions as equivalent in-product work. It also says credit budgets are not available on the developer platform yet.

Status warning: Clay describes Workflows, the agent-built multi-step runs, as Alpha on its developer pages and as Beta on its university page. Treat them as unstable. Clay-managed and custom functions are the stable option for production.

What is Clay's MCP server, and which one is official?

MCP, the Model Context Protocol, is a standard way for an AI assistant to call tools. Clay's university docs say it is how Clay connects a workspace to Claude, ChatGPT, Microsoft Copilot and Glean. Clay's own MCP guide says you add Clay from Claude's Connectors page (on Claude Enterprise an admin enables it first), and that new accounts get 500 free Clay credits on first connect. Scalekit, a third party, dates the Claude connector to 26 January 2026.

What the connector exposes is the point of difference from the Public API. Per Scalekit's analysis, it covers finding and enriching companies and contacts, running custom Functions, reading task status and checking credits. It has no batch runs, no table queries and no webhooks, and it signs in with OAuth in a browser, which makes it a poor fit for headless scheduled jobs. Admins turn a Function on for reps by selecting MCP for reps on it, set a default monthly credit limit and can override it per user. Clay's docs say credit spend resets on the 1st of each month at midnight UTC and that a limit of 0 blocks further actions. Clay's MCP settings page lists these credit controls for Launch, Growth and Enterprise. Neither that page nor Clay's MCP guide states a plan requirement for the connector itself, so check your workspace.

Clay's agent plugin for Claude Code, Codex and Cursor drives Clay through the clay CLI. The plugin's own instructions tell the agent to ignore the reps MCP for automation and use the CLI instead. Some Clay developer pages that search engines index describe a local server started as clay mcp. Those pages returned 404 on 22 October 2026 and are missing from Clay's docs index, so do not build on it until Clay republishes them. Community packages need care too. The npm package @clayhq/clay-mcp is published by clay.earth, a personal contact manager and a different company from Clay (clay.com). Nothing in a directory such as mcpservers.org is endorsed by Clay.

RouteWho maintains itAuthBest for
Hosted MCP connectorClayOAuth in browserReps and analysts running Functions from Claude chat
Agent plugin plus clay CLIClayBrowser OAuth via clay login, or clay login --device on headless machinesCoding agents such as Claude Code, Codex and Cursor
Public API plus CLIClayclay-api-key headerScripts, backend jobs, scheduled runs
npm and directory packagesThird partiesVariesCheck the publisher first

How do teams drive Clay from Claude Code?

There are three honest routes, and they suit different jobs. Use the plugin and CLI when Claude Code is doing the building: it can list routines, run a function over a list of domains and read the JSON back, because the CLI returns structured output and clear exit codes. Use MCP when a person is in a chat and wants to ask for contacts or run one saved Function. Use the Public API directly when the job runs on a schedule with nobody watching.

A sensible split for a GTM engineering team is to keep the table logic in Clay, where the waterfall, Claygent steps and credit controls already live, and use the agent as the operator. The agent loads rows through a webhook, triggers Functions through the CLI, and writes results onward. That keeps the expensive, auditable steps inside Clay and the glue outside it. For no-code glue, n8n and Make can POST to a Clay webhook URL and call the Public API over plain HTTP.

What do worked examples of each route look like?

Example 1, pushing leads in with a webhook. Add a Monitor webhook source, copy the URL and send one test row: curl -X POST "<your-webhook-url>" -H "Content-Type: application/json" -d '{"domain":"example.com","company":"Example Ltd"}'. A row appears with a column per JSON key. Send leads in batches that respect the processing rate, stay well under 100KB a payload, and track your submission count yourself, because Clay does not show how close you are to 50,000.

Example 2, calling an external API from a table. Add an HTTP API enrichment, choose GET, put the endpoint in the URL with the domain column as a query parameter, add your API key as a saved header account, and set the response path to the one field you need, such as an employee count. Test on one row, set a rate limit that matches the vendor's own, and add a condition so it only runs when the domain is filled. Where a native Clay integration exists, it is usually simpler. The waterfall enrichment guide covers ordering providers.

Example 3, getting results out to a CRM. There are four options. The simplest is Clay's native CRM sync, which the pricing page lists under Growth. The second is an HTTP API column that POSTs a row to a CRM endpoint, which suits Attio or HubSpot records when you want control over field mapping. The third is to run a Function through the Public API and write the returned JSON to the CRM from your own code, using the run-finished webhook as the trigger. The fourth, Enterprise only, is reading tables through the structured query endpoint, which is capped at 100 records a request and needs the table id in advance because there is no list-tables endpoint.

What do the Clay API and MCP cost, and which plan do you need?

There is no separate API fee. Clay's API and CLI page says both paths consume the same credits and Actions as equivalent in-product work, and that using the plugin has no additional cost. What changes by route is the plan gate, summarised below as of October 2026.

RoutePlan, per Clay's own pagesCost model
Inbound webhookPricing page lists webhooks on Growth and Enterprise; 50,000 submissions per sourceEach row enriched counts as Actions
HTTP API columnGrowth and Enterprise per the pricing pageActions, per third-party guides; check your workspace usage
Public API and CLIStated as all plans, including Free and trialSame credits and Actions as in-product
Table reads and queriesEnterpriseNot metered on the pages checked
MCP for repsNot stated; credit controls listed on Launch, Growth and EnterpriseSame credits as in-product, with per-user monthly limits

Prices as of October 2026: Growth starts at $495 a month billed monthly or $446 billed annually, and Launch at $185 or $167, so the webhook and HTTP API gate is the difference between roughly $185 and $495 a month at the entry tier. Those headline figures are the smallest Actions tier plus the smallest Data Credits tier (for Growth, $205 plus $290 billed monthly, or $185 plus $261 billed annually), so heavier usage costs more. Confirm on the live pricing page. Searches through the API have their own caps: Free gets 50 results per request and 100 results per rolling 30 days, current paid plans 500 per request and 1,000,000 per 30 days, and Enterprise 10,000,000 per 30 days. Going over returns HTTP 402. Clay's University API page still shows older totals (1 million a year on paid self-serve, 10 million a year on Enterprise), so treat the developer docs as current and check your own tier. Credit budgets do not yet exist on the developer platform, so a runaway script can spend your credits until you stop it. See the full Clay pricing breakdown.

When should you build this yourself, and when should you hire help?

Wire the webhook and a single HTTP column yourself if you have an engineer: it is an afternoon of work and the Clay docs are clear. The cost shows up later, in the 50,000 cap, the missing spend circuit breaker, the user-tied API key and the Alpha features that change. If those matter, a Clay specialist will design around them from the start.

Tentt is a GTM engineering agency that builds Clay systems into a client's own workspace, including CRM sync, as a 30-day One-System Build, and then hands them over with training and documentation. Tentt is not a Clay partner. If you would rather not own the plumbing, see the Clay agency page or the CRM setup service.

Get a Clay system built

Talk to Tentt about your stack

Clay questions people ask

Does Clay have an API?

Yes, several. As of October 2026 Clay offers inbound webhooks, an HTTP API column, a Public API at api.clay.com/public/v0 with a clay-api-key header, a CLI and plugin, and MCP. The Public API documents no endpoint for writing table rows, so inbound webhooks remain the way to push data in from code.

Is there an official Clay MCP server?

Yes. Clay's hosted MCP connector works in Claude, ChatGPT, Microsoft Copilot and Glean. It signs in with OAuth and runs Functions an admin has enabled for MCP. For Claude Code, Clay's own plugin uses the clay CLI instead. The npm package @clayhq/clay-mcp belongs to clay.earth, a different company.

Do I need the Growth plan for Clay webhooks?

Clay's pricing page lists webhooks and the HTTP API under Growth and Enterprise, so plan on Growth, from $495 a month billed monthly, as of October 2026. The webhook doc itself does not state a plan, so check the pricing page for your account.

What is the Clay webhook limit?

Clay's docs say a webhook source is limited to 50,000 submissions and deleting rows does not reset it. Enterprise can enable auto-delete for unlimited submissions. Other plans create a new webhook. Community replies add about 10 records a second and a 100KB payload, which are not in the docs.

Can Claude Code use Clay?

Yes. Clay's quickstart supports Claude Code, Codex and Cursor through its plugin, which installs the clay CLI and signs you in via the browser. Claude Code can then list and run Clay functions and read JSON results. The plugin needs a coding agent with a shell, not a general chat app.

Related guides

Tools mentioned in this guide

Want a GTM engineering system built for you?

Tentt builds signal-driven outbound, enrichment and CRM systems into B2B companies' stacks. Or start free with the resources from every video.

Sources

Checked on 22 October 2026.

  1. Clay developer docs: quickstart
  2. Clay developer docs: documentation index
  3. Clay developer docs: running functions through the Public API
  4. Clay developer docs: batch runs
  5. Clay developer docs: Public API webhooks
  6. Clay developer docs: rate limits
  7. Clay developer docs: CLI basics
  8. Clay developer docs: tables
  9. Clay University: API and CLI
  10. Clay University: webhook integration guide
  11. Clay University: HTTP API integration overview
  12. Clay University: MCP settings
  13. Clay pricing page
  14. Scalekit: Clay MCP vs Clay API (third party, 10 August 2026)
  15. Clay developer docs: searches and limits
  16. Clay agent plugins on GitHub
  17. Clay: Clay MCP guide
  18. Clay developer docs: authentication