Clay connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Clay credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Clay uses OAuth 2.1 with Dynamic Client Registration (DCR) and PKCE. Scalekit registers an OAuth client with Clay automatically on first connection. Complete this setup once per environment to authorize Scalekit to proxy requests to the Clay MCP server at https://api.clay.com/v3/mcp.

   1. Create a connection in Scalekit

      In the Scalekit dashboard, go to AgentKit > Connections. Find Clay and click Create.

      Note the Connection name — you use this as connection_name in your code (for example, claymcp).

   2. Authorize the connection

      Generate an authorization link for a user and open it in a browser. Clay prompts the user to grant the requested scopes. After the user approves, the connected account becomes active and Scalekit manages token refresh automatically.

   3. Verify the connection is active

      In the Scalekit dashboard, open AgentKit > Connections > Clay and confirm the connected account shows status Active. If it shows Pending, the user has not yet completed the authorization flow.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'claymcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Clay:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'claymcp_get_credits_available',
     toolInput: { rationale: 'YOUR_RATIONALE' },
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "claymcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Clay:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={"rationale":"YOUR_RATIONALE"},
       tool_name="claymcp_get_credits_available",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Points add company data, add contact data — Add data points to companies in an existing search
• Accounts ask question about — Ask a natural language question about one or more accounts available in Clay Audiences
• Company find and enrich, find and enrich contacts at — Find and enrich a single company by domain or LinkedIn URL
• List find and enrich, subroutines — Find and enrich specific named contacts at their companies
• Get credits available, subroutine input options, task — Check if credits are available for the workspace
• Query objects — Query audience accounts, contacts, or deals using natural language

Common workflows

Enrich a company and its key contacts

Use claymcp_find_and_enrich_company to look up a company by domain, then claymcp_find_and_enrich_contacts_at_company to find decision-makers there. Check the task status with claymcp_get_task before reading results — enrichment runs asynchronously.

Check task status before reading results

Enrichment tools return a taskId. Poll claymcp_get_task until status is completed before reading the enriched data.

Node.js

// Step 1 — enrich the company
const companyTask = await actions.executeTool({
  connectionName: 'claymcp',
  identifier: 'user_123',
  toolName: 'claymcp_find_and_enrich_company',
  toolInput: {
    domain: 'clay.com',
    rationale: 'Researching Clay for outbound prospecting',
  },
});
const taskId = companyTask.taskId;

// Step 2 — find contacts at the company
const contactTask = await actions.executeTool({
  connectionName: 'claymcp',
  identifier: 'user_123',
  toolName: 'claymcp_find_and_enrich_contacts_at_company',
  toolInput: {
    taskId,
    filters: { seniority: ['VP', 'Director', 'C-Suite'] },
    rationale: 'Finding decision-makers for outbound',
  },
});
console.log('Contact task:', contactTask.taskId);

Python

# Step 1 — enrich the company
company_task = actions.execute_tool(
    connection_name="claymcp",
    identifier="user_123",
    tool_name="claymcp_find_and_enrich_company",
    tool_input={
        "domain": "clay.com",
        "rationale": "Researching Clay for outbound prospecting",
    },
)
task_id = company_task["taskId"]

# Step 2 — find contacts at the company
contact_task = actions.execute_tool(
    connection_name="claymcp",
    identifier="user_123",
    tool_name="claymcp_find_and_enrich_contacts_at_company",
    tool_input={
        "taskId": task_id,
        "filters": {"seniority": ["VP", "Director", "C-Suite"]},
        "rationale": "Finding decision-makers for outbound",
    },
)
print("Contact task:", contact_task["taskId"])

Check credit balance before a bulk enrichment

Use claymcp_get_credits_available to confirm your workspace has enough credits before kicking off a large enrichment run.

Node.js

const credits = await actions.executeTool({
  connectionName: 'claymcp',
  identifier: 'user_123',
  toolName: 'claymcp_get_credits_available',
  toolInput: { rationale: 'Checking credits before bulk enrichment' },
});
console.log('Credits available:', credits.creditsAvailable);

Python

credits = actions.execute_tool(
    connection_name="claymcp",
    identifier="user_123",
    tool_name="claymcp_get_credits_available",
    tool_input={"rationale": "Checking credits before bulk enrichment"},
)
print("Credits available:", credits["creditsAvailable"])

Run a custom subroutine on enriched contacts

List available subroutines with claymcp_list_subroutines, then run one with claymcp_run_subroutine or claymcp_run_subroutine_direct. Subroutines are custom Clay functions — they can write data or trigger workflows, so confirm with the user before running them.

Subroutines are write operations

claymcp_run_subroutine, claymcp_run_subroutine_direct, and claymcp_run_subroutine_no_mapping execute custom Clay functions that may write data or trigger downstream actions. Confirm intent with the user before calling them.

Node.js

// Step 1 — list subroutines to find the right one
const subroutines = await actions.executeTool({
  connectionName: 'claymcp',
  identifier: 'user_123',
  toolName: 'claymcp_list_subroutines',
  toolInput: { rationale: 'Listing available subroutines' },
});

// Step 2 — run a subroutine on contacts from an existing task
const result = await actions.executeTool({
  connectionName: 'claymcp',
  identifier: 'user_123',
  toolName: 'claymcp_run_subroutine',
  toolInput: {
    subroutineId: subroutines.subroutines[0].id,
    taskId: 'EXISTING_TASK_ID',
    rationale: 'Running lead scoring subroutine on enriched contacts',
  },
});
console.log('Subroutine result:', result);

Python

# Step 1 — list subroutines to find the right one
subroutines = actions.execute_tool(
    connection_name="claymcp",
    identifier="user_123",
    tool_name="claymcp_list_subroutines",
    tool_input={"rationale": "Listing available subroutines"},
)

# Step 2 — run a subroutine on contacts from an existing task
result = actions.execute_tool(
    connection_name="claymcp",
    identifier="user_123",
    tool_name="claymcp_run_subroutine",
    tool_input={
        "subroutineId": subroutines["subroutines"][0]["id"],
        "taskId": "EXISTING_TASK_ID",
        "rationale": "Running lead scoring subroutine on enriched contacts",
    },
)
print("Subroutine result:", result)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

claymcp_add_company_data_points#Add data points to companies in an existing search. Supports enriching ALL companies or specific companies via entityIds. Use for tech stack, funding, headcount, competitors, or any custom research question about companies.4 params▾

Add data points to companies in an existing search. Supports enriching ALL companies or specific companies via entityIds. Use for tech stack, funding, headcount, competitors, or any custom research question about companies.

NameTypeRequiredDescription

dataPointsarrayrequiredThe data points to apply to the company

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

taskIdstringrequiredThe task ID identifying the search to add company data points to

entityIdsarrayoptionalOptional. Array of entityIds to enrich. When omitted, enriches all companies.

claymcp_add_contact_data_points#Add data points to contacts in an existing search. Supports enriching ALL contacts or specific contacts via entityIds. Use for emails, phone numbers, work history, thought leadership, or any custom research question about contacts.4 params▾

Add data points to contacts in an existing search. Supports enriching ALL contacts or specific contacts via entityIds. Use for emails, phone numbers, work history, thought leadership, or any custom research question about contacts.

NameTypeRequiredDescription

dataPointsarrayrequiredThe data points to apply to the contacts

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

taskIdstringrequiredThe task ID identifying the search to add contact data points to

entityIdsarrayoptionalOptional. Array of entityIds to enrich. When omitted, enriches all contacts.

claymcp_ask_question_about_accounts#Ask a natural language question about one or more accounts available in Clay Audiences. An AI agent analyzes account data including contacts, opportunities, Gong calls, and emails to answer the question.3 params▾

Ask a natural language question about one or more accounts available in Clay Audiences. An AI agent analyzes account data including contacts, opportunities, Gong calls, and emails to answer the question.

NameTypeRequiredDescription

accountIdsarrayrequiredAccount IDs to analyze (1-10)

questionstringrequiredNatural language question about the accounts

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

claymcp_find_and_enrich_company#Find and enrich a single company by domain or LinkedIn URL. Use for prospecting publicly available company info (funding, competitors, tech stack, etc.). Returns a taskId for follow-up enrichment.3 params▾

Find and enrich a single company by domain or LinkedIn URL. Use for prospecting publicly available company info (funding, competitors, tech stack, etc.). Returns a taskId for follow-up enrichment.

NameTypeRequiredDescription

companyIdentifierstringrequiredCompany identifier (domain like "clay.com" or LinkedIn URL like "https://www.linkedin.com/company/grow-with-clay")

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

companyDataPointsarrayoptionalOptional data points to enrich during search creation

claymcp_find_and_enrich_contacts_at_company#Search for contacts at a company by role, title, name, or department. Supports filtering by job title keywords, locations, tenure, certifications, languages, and more. Returns a taskId for follow-up enrichment.4 params▾

Search for contacts at a company by role, title, name, or department. Supports filtering by job title keywords, locations, tenure, certifications, languages, and more. Returns a taskId for follow-up enrichment.

NameTypeRequiredDescription

companyIdentifierstringrequiredThe company identifier to search for company and contacts. Either a domain (e.g. "clay.com") or a LinkedIn URL (e.g. "https://www.linkedin.com/company/grow-with-clay").

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

contactFiltersobjectoptionalNo description.

dataPointsobjectoptionalOptional data points to enrich during search creation

claymcp_find_and_enrich_list_of_contacts#Find and enrich specific named contacts at their companies. Use when you have a list of specific people by name (e.g. "John Smith at OpenAI"). Returns a taskId for follow-up enrichment.3 params▾

Find and enrich specific named contacts at their companies. Use when you have a list of specific people by name (e.g. "John Smith at OpenAI"). Returns a taskId for follow-up enrichment.

NameTypeRequiredDescription

contactIdentifiersarrayrequiredArray of contact identifiers to find and enrich, with their company identifiers

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

dataPointsobjectoptionalOptional data points to enrich during search creation

claymcp_get_credits_available#Check if credits are available for the workspace. Returns hasWorkspaceCredits, hasSalesRepCredits, and (when credit budgets are enabled) hasBudgetCredits.1 param▾

Check if credits are available for the workspace. Returns hasWorkspaceCredits, hasSalesRepCredits, and (when credit budgets are enabled) hasBudgetCredits.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

claymcp_get_subroutine_input_options#Fetch the available dropdown options for a subroutine input that has a configured options source.3 params▾

Fetch the available dropdown options for a subroutine input that has a configured options source.

NameTypeRequiredDescription

inputNamestringrequiredThe name of the input whose options to fetch.

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

subroutine_idstringrequiredThe ID of the subroutine.

claymcp_get_task#Get task status and results by task ID. Handles all task types (search, direct) and returns the current state. Accepts universal mcp-task-* IDs and legacy cgas-search-id-* IDs.2 params▾

Get task status and results by task ID. Handles all task types (search, direct) and returns the current state. Accepts universal mcp-task-* IDs and legacy cgas-search-id-* IDs.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

taskIdstringrequiredThe task ID to retrieve (mcp-task-* or legacy cgas-search-id-*)

claymcp_get_task_context#Retrieve the current state of a task — all entities, enrichment values, and statuses. Call this to get actual enrichment results (emails, phone numbers, work history, custom data points) after a search or enrichment operation.3 params▾

Retrieve the current state of a task — all entities, enrichment values, and statuses. Call this to get actual enrichment results (emails, phone numbers, work history, custom data points) after a search or enrichment operation.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

taskIdstringrequiredThe task ID to retrieve (mcp-task-* or legacy cgas-search-id-*)

entityIdsarrayoptionalOptional. Pass specific entity IDs to retrieve only those entities. Leave empty or omit to retrieve all entities for the task.

claymcp_list_subroutines#List available custom functions in the workspace. Call this to see their required inputs before using run_subroutine.1 param▾

List available custom functions in the workspace. Call this to see their required inputs before using run_subroutine.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

claymcp_query_objects#Query audience accounts, contacts, or deals using natural language. Translates plain language descriptions into structured filters and returns matching entities with field values from Clay Audiences.6 params▾

Query audience accounts, contacts, or deals using natural language. Translates plain language descriptions into structured filters and returns matching entities with field values from Clay Audiences.

NameTypeRequiredDescription

querystringrequiredNatural language description of what to filter, e.g. "tech companies with 500+ employees"

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

audienceNamestringoptionalName of a saved audience segment to scope results to

limitintegeroptionalMax rows to return (default 50)

offsetintegeroptionalPagination offset (default 0)

onlyMinebooleanoptionalWhen true, restrict account results to the caller's Salesforce-owned accounts

claymcp_run_subroutine#Execute a custom function on contacts/companies from an existing search. Use when you have a taskId from a previous search and want to run a subroutine on all or specific contacts. Requires fieldMapping to map entity fields to subroutine inputs.5 params▾

Execute a custom function on contacts/companies from an existing search. Use when you have a taskId from a previous search and want to run a subroutine on all or specific contacts. Requires fieldMapping to map entity fields to subroutine inputs.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

subroutine_idstringrequiredThe ID of the subroutine to execute. Get this from list_subroutines.

taskIdstringrequiredRequired. The taskId from the existing search task to add results to.

entityIdsarrayoptionalOptional. Array of entityIds to run on. When omitted with fieldMapping, runs on all contacts.

fieldMappingobjectoptionalRequired for batch mode. Format: { "entityField": "subroutineInput" }. KEY = entity field name, VALUE = subroutine input name.

claymcp_run_subroutine_direct#Execute a custom function directly with provided inputs, without needing an existing task or entityIds. Use when the user provides specific input values (LinkedIn URL, name, email, etc.) and wants to run a function on that data directly.3 params▾

Execute a custom function directly with provided inputs, without needing an existing task or entityIds. Use when the user provides specific input values (LinkedIn URL, name, email, etc.) and wants to run a function on that data directly.

NameTypeRequiredDescription

inputsobjectrequiredThe actual input values for the subroutine. Keys must match the input names from list_subroutines.

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

subroutine_idstringrequiredThe ID of the subroutine to execute. Get this from list_subroutines.

claymcp_run_subroutine_no_mapping#Run a custom subroutine on search entities. The backend automatically generates the field mapping. Requires a subroutine_id and taskId from an existing search.5 params▾

Run a custom subroutine on search entities. The backend automatically generates the field mapping. Requires a subroutine_id and taskId from an existing search.

NameTypeRequiredDescription

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

subroutine_idstringrequiredThe ID of the subroutine to execute.

taskIdstringrequiredThe taskId from the existing search.

entityIdsarrayoptionalOptional. Array of entityIds to run on. When omitted, runs on all entities.

inputsobjectoptionalOptional. Explicit values for inputs the user selected (e.g. dropdown pickers), keyed by input name.

claymcp_track_event#Track an analytics event with optional properties.3 params▾

Track an analytics event with optional properties.

NameTypeRequiredDescription

eventNamestringrequiredThe name of the event to track

rationalestringrequiredAlways provide a brief explanation of why you are calling this tool

propertiesobjectoptionalAdditional properties to include with the event