Connect your AI Agents to Clay in minutes
Available tools
get_current_user
Get the Clay user and workspace tied to the API key. Use to confirm which workspace tools will operate on.
execute_routine
Run a Clay routine against 1-100 items and get a routinerunid. The run is async, so poll getroutinerun with that ID for results. Each item needs a caller-defined id and an inputs object. Find routineid at app.clay.com/functions > select the function > Details, and pass it prefixed, as 'function:t...'.
get_routine_run
Fetch progress and results for a routine run by routinerunid. While running, status is 'in_progress' and data is empty; once done, status is 'complete' with per-item results. Page with cursor while a cursor is returned.
create_batch_upload_url
Issue a presigned PUT URL for uploading a batch input JSONL file for a routine. Returns uploadurl (PUT the JSONL to it, client-side) and fileid. Then call startbatchrun with the fileid. Use for batches larger than executeroutine's 100-item limit. routineid must be prefixed, as 'function:t...'.
start_batch_run
Start an async batch routine run over a JSONL file already uploaded via createbatchuploadurl. Takes routineid and the fileid from that call; returns a routinerunid. Poll results with getbatch_run.
get_batch_run
Fetch progress and outcome for a batch run by routinerunid (from startbatchrun). While running, status is 'inprogress' with total/finished counts. Once status is 'complete', GET the returned resulturl to download the results JSONL. On 'validationfailed' or 'processingfailed', error explains why. Results are not paged and not returned inline.
list_search_fields
List the filter fields available for a search sourcetype ('people' or 'companies'), plus Clay's usage guidance and example filter payloads. Call this before createsearch to learn valid filter keys and values.
create_search
Create a people or company search from structured filters. Returns a searchid; page results with runsearch. Discover valid filter keys/values with listsearchfields first.
run_search
Run a search created by createsearch and return the next page of matching records. Call repeatedly while hasmore is true to page through all results. Each call advances the search and consumes billable search records, so it is not safe to retry blindly; period_quota reports what is left.
get_search_query_reference
Get Clay's advanced search query reference (markdown): the queryable fields and query grammar. Call this before createquerysearch to author a valid query. Beta.
create_query_search
Create a people or company search from a Clay advanced search query string. Clay detects the source type from the query and returns it with a searchid; page results with runquerysearch. Call getsearchqueryreference first for valid fields and grammar. Count-mode and jobs queries are not supported. Beta.
run_query_search
Return the next page of records for a search created by createquerysearch. Call repeatedly while hasmore is true. When hasmore is false, exhaustion_reason says whether the query ran out of results or hit Clay's per-query cap. Each call advances the search and consumes billable search records. Beta.
query_tables
Run a structured query across 1-5 Clay tables (Enterprise). Supports select, filter (AND/OR/NOT), join, groupby, and orderby. Table IDs come from a table's settings in Clay. Page with cursor while a cursor is returned.
validate_credential
Validate the Clay API key with a lightweight call to /me. Returns success plus a short message.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's Clay MCP server
FAQs on using Merge's Clay MCP server
What is a Clay MCP?
It's an MCP server that lets your agents access data and functionality from Clay via tools. Your agents can invoke these tools to enrich a company or contact record, run a waterfall against multiple data providers, build a prospect list from structured search filters, kick off a batch enrichment routine, and more.
Clay offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.
How can I use the Clay MCP server?
The use cases naturally depend on the agent you've built, but here are a few common ones:
- Automated lead enrichment: a new lead lands in Salesforce, and your agent triggers a Clay routine to enrich the record with firmographic and contact data, then writes the results back to the CRM field by field
- Waterfall cost monitoring: your agent checks the status of an in-flight enrichment waterfall, flags any provider that's burning credits without returning matches, and reports the outcome so ops can adjust the provider order
- Slack-triggered prospecting: a rep asks Claude in Slack to build a list of fintech accounts under 200 employees, and your agent runs a Clay search, pages through the results, and drops the matches into a table
- GTM data cross-referencing: your agent queries multiple Clay tables to reconcile enrichment results against a target account list before it hands qualified leads off to a scoring workflow
What are popular tools for Clay's MCP server?
Here are some of the most commonly used tools:
execute_routine: runs a Clay routine against 1-100 items asynchronously. Useful for agents that need to kick off a multi-step enrichment or waterfall workflow without sitting in the Clay UI waiting on it
create_search: builds a people or company search from structured filters like title, industry, or headcount. Use this when an agent needs to turn a plain-language request into a defined search against Clay's data
run_search: executes a search created withcreate_searchand pages through the matching records. Call this when an agent needs the actual list of people or companies back, not just a search definition
query_tables: runs a structured query across up to five Clay tables on Enterprise workspaces. Good for workflows that need to cross-reference enrichment results stored across multiple tables before acting on them
start_batch_run: kicks off a batch routine run against an uploaded JSONL file of input rows. Helpful when an agent needs to enrich or process a large list in one call instead of row by row
get_routine_run: fetches the progress and results of a routine execution. Useful for agents that need to poll whether an enrichment job finished before consuming its output
What makes Merge Agent Handler's Clay MCP server better than alternative Clay MCP servers?
There are several reasons to use Merge Agent Handler's Clay MCP server over building or using an alternative:
- Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Clay, this means you can prevent enrichment API keys, contact emails and phone numbers, and company financial data from being exposed even when the agent has broad read access
- Managed authentication and credentials: Merge stores and refreshes Clay credentials on your behalf. You never expose raw API keys or OAuth tokens to an agent or manage token rotation manually
- Real-time observability and audit trail: every tool call made against Clay is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what an agent read or wrote without instrumenting anything yourself
- Tool Packs and controlled access: bundle specific Clay tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more
How can I start using Merge Agent Handler's Clay MCP server?
You can take the following steps:
1. Create or log into your Merge Agent Handler account.
2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.
3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.
4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Clay and complete the auth flow. Merge stores and manages the credentials going forward.
5. Open a Claude Code session and start querying Clay data directly. The first time you use a Clay tool, a Magic Link may appear to complete connector authentication.
If you want to connect Merge Agent Handler's Clay MCP with internal or customer-facing agentic products, you can follow the steps in our docs.
Can employees use Merge to connect their AI tools to Clay?
Yes, Merge for Workforce lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to Clay without bypassing IT governance.
IT can provision access by role or group via SCIM. A revenue operations analyst, for example, gets Clay access to run enrichment waterfalls, Salesforce to update account records, and Slack to notify the sales team; while a demand generation manager gets Clay access to build targeted prospect lists, HubSpot to sync campaign segments, and Google Sheets to track list coverage.
Every tool call an employee's AI makes to Clay is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
