Skip to main content
Clay MCP logo
  • Category: model context protocol
  • Auth: DCR_OAUTH
  • Composio-managed OAuth available? No
  • Tools: 17
  • Triggers: 0
  • Slug: CLAY_MCP
  • Version: 20261018_00

Tools

Slug: CLAY_MCP_ADD_COMPANY_DATA_POINTSAdd data points to companies in an existing search. Supports enriching ALL companies or specific companies via entityIds.

Quick Reference

  • This tool: Enrich COMPANIES with funding, tech stack, headcount, etc.
  • add-contact-data-points: Enrich CONTACTS with emails, work history, etc.
  • Requires a taskId from a previous find-and-enrich-* tool call
  • Use entityIds to enrich specific companies — do NOT create a new search to enrich one company from an existing search
  • ANY research question about companies = call this tool with a Custom data point

IMPORTANT: When to Call This Tool

Check before enriching: If the user asks about a specific company’s data (e.g. “what’s their tech stack?”), call get-task-context FIRST — the user may have already enriched it through the widget. Only call this tool if get-task-context shows the enrichment hasn’t been run.Call this tool whenever the user asks to FETCH or ADD new information about companies, including:
  • Standard data points (tech stack, funding, headcount, etc.)
  • Any open-ended research question — use Custom type for these
Do NOT try to answer company research questions from your own knowledge. ALWAYS call this tool or get-task-context to fetch the data.Examples that MUST trigger this tool:
  • “What’s their tech stack?” → Standard type
  • “Find recent product announcements” → Custom type
  • “Get me their latest news” → Custom type
  • “What’s their revenue model?” → Custom type
  • “Find their competitors” → Custom type
  • “Any recent acquisitions?” → Custom type

Parameters

taskId (required)

The task ID returned from find-and-enrich-company, find-and-enrich-contacts-at-company, or find-and-enrich-list-of-contacts.
  • Do NOT fabricate a taskId—use the one from the prior search
  • If no search exists yet, prompt the user to search first

dataPoints (required)

Array of data points to add.
  • Standard: { type: “<DataPointType>” }
  • Custom: { type: “Custom”, customDataPoint: “<brief description>” }
Available standard types: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest FundingCustom type: Use for ANY research question not covered by standard types. Examples:
  • “recent product announcements” → { type: “Custom”, customDataPoint: “recent product announcements” }
  • “B2B vs B2C classification” → { type: “Custom”, customDataPoint: “B2B vs B2C classification” }
  • “company founders” → { type: “Custom”, customDataPoint: “company founders” }

entityIds (optional)

Array of entityIds to enrich. When omitted, enriches all companies in the search.
  • Use the entityId values from the company data returned by a previous search tool call
  • Useful when the user wants to enrich specific companies

Examples

Response Behavior

  • Confirm briefly: “Fetching [data point] for [company/companies].”
  • For single-company requests, name the company instead of saying “all companies.” Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Input Parameters

string
required
The task ID identifying the search to add company data points to
array
Optional. Array of entityIds to enrich. When omitted, enriches all companies.
array
required
The data points to apply to the company
Slug: CLAY_MCP_ADD_CONTACT_DATA_POINTSAdd data points to contacts in an existing search. Supports enriching ALL contacts or specific contacts via entityIds.

Quick Reference

  • This tool: Enrich CONTACTS with emails, work history, etc.
  • add-company-data-points: Enrich COMPANIES with funding, tech stack, headcount, etc.
  • Requires a taskId from a previous find-and-enrich-* tool call
  • Use entityIds to enrich specific contacts — do NOT create a new search to enrich one person from an existing search
  • ANY research question about contacts = call this tool with a Custom data point

IMPORTANT: When to Call This Tool

Check before enriching: If the user asks about a specific contact’s data (e.g. “what’s Patrick’s email?”), call get-task-context FIRST — the user may have already enriched it through the widget. Only call this tool if get-task-context shows the enrichment hasn’t been run.Call this tool whenever the user asks to FETCH or ADD new information about contacts, including:
  • Standard data points (email, work history, etc.)
  • Any open-ended research question — use Custom type for these
Do NOT try to answer contact research questions from your own knowledge. ALWAYS call this tool or get-task-context to fetch the data.Examples that MUST trigger this tool:
  • “Get their emails” → Standard type
  • “Find their recent publications” → Custom type
  • “What have they posted on LinkedIn?” → Custom type
  • “Summarize their career trajectory” → Custom type
  • “Any recent job changes?” → Custom type
  • “Score them against my ICP” → Custom type

Parameters

taskId (required)

The task ID returned from find-and-enrich-contacts-at-company or find-and-enrich-list-of-contacts.
  • Do NOT fabricate a taskId—use the one from the prior search
  • If no search exists yet, prompt the user to search first

dataPoints (required)

Array of data points to add.
  • Standard: { type: “<DataPointType>” }
  • Custom: { type: “Custom”, customDataPoint: “<brief description>” }
Available standard types: Email, Summarize Work History, Find Thought LeadershipCustom type: Use for ANY research question not covered by standard types. Examples:
  • “recent publications” → { type: “Custom”, customDataPoint: “recent publications” }
  • “LinkedIn activity” → { type: “Custom”, customDataPoint: “recent LinkedIn posts” }
  • “ICP fit score” → { type: “Custom”, customDataPoint: “ICP fit score based on seniority and tenure” }

entityIds (optional)

Array of entityIds to enrich. When omitted, enriches all contacts in the search.
  • Use the entityId values from the contact data returned by a previous search tool call
  • Useful when the user wants to enrich specific contacts (e.g., “get John’s email”)

Examples

Response Behavior

  • Confirm briefly: “Fetching [data point] for all contacts.”
  • For single-contact requests, name the contact instead of saying “all contacts.” Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Input Parameters

string
required
The task ID identifying the search to add contact data points to
array
Optional. Array of entityIds to enrich. When omitted, enriches all contacts.
array
required
The data points to apply to the contacts
Slug: CLAY_MCP_ASK_QUESTION_ABOUT_ACCOUNTSAsk a natural language question about one or more accounts available in Clay Audiences. Depending on your workspace settings and whether Salesforce owner data is available, this may be limited to accounts you own in Salesforce. An AI agent analyzes account data including contacts, opportunities, Gong calls, and emails to answer your question.IMPORTANT: Both “accountIds” and “question” parameters are REQUIRED — you must always provide both when calling this tool.

Quick Reference

  • This tool: Ask questions or get analysis about specific accounts (e.g., “What’s the status of this deal?”, “Who are the key stakeholders?”)
  • query-objects: Call this first to get account entity IDs before calling this tool, unless you already have account IDs. Find and list accessible accounts by natural-language filters.
  • find-and-enrich-company: Only for prospecting publicly available company info. Do NOT use find-and-enrich-company when the user is asking about their own accounts or deals; use this tool instead.
  • For ambiguous queries (e.g., “Tell me about Acme”), call query-objects first. If the account exists, use this tool. If not, fall back to find-and-enrich-company.

Prerequisites

You need the accountId (numeric) for each account you want to ask about. If you don’t have it:
  1. Call query-objects to find accounts by name or other natural-language filters. Use onlyMine: true when the user asks about “my” accounts or accounts they personally own; omit it when they ask about accounts in general.
  2. Use the returned account entityId values as accountIds
Access to specific accounts depends on your workspace settings. Some workspaces allow questions about any account in the audience, while others restrict questions to accounts you own in Salesforce when Salesforce owner data is available.

Parameters

accountIds (required — MUST be provided)

Array of numeric account IDs from returned account entityId values in the query-objects response. Supports 1-10 accounts.
  • For single-account questions: provide one ID (e.g., [12345])
  • For multi-account questions (e.g., comparisons): provide multiple IDs (e.g., [12345, 67890]). The tool returns individual analyses for each account — you should synthesize and compare the results yourself.

question (required — MUST be provided)

A natural language question about the account(s). Be specific for best results.

Correct Usage

You MUST always call this tool with BOTH parameters like this: { “accountIds”: [12345], “question”: “What is the deal status?” }

Examples

Response Behavior

  • Returns a detailed text answer from the AI agent based on each account’s data
  • The agent analyzes contacts, opportunities, Gong call transcripts, and emails
  • For multi-account requests, individual analyses are returned per account — you are responsible for comparing or synthesizing the results
  • This tool may take longer than other tools due to the depth of analysis

Input Parameters

string
required
array
required
Slug: CLAY_MCP_FIND_AND_ENRICH_COMPANYFind and enrich a single company by domain or LinkedIn URL.

Quick Reference

  • This tool: Prospect and research PUBLICLY AVAILABLE company info (e.g., “Tell me about Stripe”, “What’s OpenAI’s funding?”). This is for prospecting external data, NOT for querying the user’s own account data.
  • find-and-enrich-contacts-at-company: Find TYPES of people (e.g., “engineers at Stripe”)
  • find-and-enrich-list-of-contacts: Find SPECIFIC named people (e.g., “John Smith at Stripe”)
  • query-objects + ask-question-about-accounts: Ask about the user’s OWN accounts, deals, CRM data, or relationships (e.g., “What’s happening with my Acme deal?”, “How’s our relationship with Stripe?”)
  • Do NOT use if user wants to find people; use the contact tools instead
  • Do NOT use if user is asking about their own accounts, deals, opportunities, or CRM data; use query-objects and ask-question-about-accounts instead
  • For ambiguous queries about a company (e.g., “Tell me about Acme”), prefer checking query-objects first. Only use this tool if the account is not found or the user is explicitly prospecting.

Parameters

companyIdentifier (required)

Domain (e.g., “stripe.com”) or LinkedIn company URL. Company names alone will fail.
  • Convert known companies: “Stripe” → “stripe.com”
  • If ambiguous (e.g., “Delta”), ask the user to clarify

companyDataPoints (optional)

Enrich the company when creating a NEW search. For existing searches, use add-company-data-points instead.⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user’s message specifically requests that data.
  • “Tell me about Stripe” → NO data points
  • “What’s Stripe’s funding?” → add Latest Funding (user explicitly asked)
  • Do NOT add Headcount Growth, Recent News, or any other data point “to be helpful” — only what the user asked for
DataPoint format:
  • Standard: { type: “<DataPointType>” }
  • Custom: { type: “Custom”, customDataPoint: “<brief description>” }
Important: Only include customDataPoint field when type is “Custom”Available companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding

Examples

Response Behavior

  • Summarize the company result briefly (e.g., “Found Stripe”).
  • The tool returns a taskId for use with add-company-data-points, custom functions, or get-task-context. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Input Parameters

array
Optional data points to enrich during search creation
string
required
Company identifier (domain like “clay.com” or LinkedIn URL like “https://www.linkedin.com/company/grow-with-clay”)
Slug: CLAY_MCP_FIND_AND_ENRICH_CONTACTS_AT_COMPANYSearch for contacts at a company by role, title, name, or department.

Quick Reference

  • This tool: Find TYPES of people (e.g., “engineers at Stripe”, “VPs at OpenAI”) or search by name (e.g., “someone named Urmanov at Allstate”)
  • find-and-enrich-list-of-contacts: Find SPECIFIC named people (e.g., “John Smith at Stripe”)
  • Follow-ups: ALWAYS re-call this tool—never filter results in chat. When ambiguous, ask the user.

Parameters

companyIdentifier (required)

Domain (e.g., “stripe.com”) or LinkedIn company URL. Company names alone will fail.
  • Convert known companies: “Stripe” → “stripe.com”
  • If ambiguous (e.g., “Delta”), ask the user to clarify

contactFilters (optional)

Narrow results. Only add filters the user explicitly requests.Rules:
  • Filters combine with AND; values within arrays combine with OR
  • Keep compound titles as ONE string: “VP Finance” → [“VP Finance”], NOT [“VP”, “Finance”]
  • Use specific terms to avoid false matches:
    • ✓ “Software Engineer” not “Engineer” (matches Sales Engineer, etc.)
    • ✓ “Product Manager” not “Manager” (matches Account Manager, etc.)
Available filters:

dataPoints (optional)

Enrich contacts/companies when creating a NEW search. For existing searches, use add-contact-data-points or add-company-data-points instead.⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user’s message specifically requests that data.
  • “Find engineers at Stripe” → NO data points
  • “Find engineers at Stripe and get their emails” → add Email (user explicitly asked)
  • “Tell me about OpenAI” → NO data points
  • Do NOT add Headcount Growth, Recent News, or any other data point “to be helpful” — only what the user asked for
Structure: { contactDataPoints?: DataPoint[], companyDataPoints?: DataPoint[] }DataPoint format:
  • Standard: { type: “<DataPointType>” }
  • Custom: { type: “Custom”, customDataPoint: “<brief description>” }
Important: Only include customDataPoint field when type is “Custom”Available contactDataPoints: Email, Summarize Work History, Find Thought LeadershipAvailable companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest FundingExamples:

Examples

Handling Follow-ups

ANY search modification requires re-calling this tool. Never filter in chat.Interpret user intent:
  • “also/too/as well” → ADD to existing filters
  • “only/just” → NARROW within current context (e.g., “VPs only” after Finance search → “VP Finance”)
  • “actually/instead/switch” → REPLACE filters entirely
  • When ambiguous, ask the user rather than guessing
Examples:
  1. User: “Find SDRs at Verkada” → { job_title_keywords: [“SDR”, “Sales Development”] } User: “Get AEs too” → ADD: { job_title_keywords: [“SDR”, “Sales Development”, “Account Executive”] }
  2. User: “Find Finance people at Ramp” → { job_title_keywords: [“Finance”] } User: “Make it VPs only” → NARROW: { job_title_keywords: [“VP Finance”] }
  3. User: “Find Finance people at Ramp” → { job_title_keywords: [“Finance”] } User: “Actually show me all VPs” → REPLACE: { job_title_keywords: [“VP”] }

Response Behavior

  • Summarize the search briefly (e.g., “Found 20 engineers at OpenAI”).
  • The tool returns a taskId for use with add-contact-data-points, add-company-data-points, custom functions, or get-task-context.
  • For emails, use add-contact-data-points with the taskId. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Zero Results

Suggest broadening in order:
  1. Remove or broaden title keywords (e.g., “Software Engineer” → “Engineer”)
  2. Remove location filter
  3. Remove tenure filter
  4. Verify company domain is correct

Input Parameters

object
Optional data points to enrich during search creation
object
string
required
The 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”).
Slug: CLAY_MCP_FIND_AND_ENRICH_LIST_OF_CONTACTSFind and enrich specific named contacts at their companies.

Quick Reference

  • This tool: Find SPECIFIC named people (e.g., “John Smith at OpenAI”, “Jane Doe at Stripe”)
  • find-and-enrich-contacts-at-company: Find TYPES of people (e.g., “engineers at Stripe”)
  • Do NOT use if user only provides company names without contact names
  • Do NOT use to enrich contacts already in an existing search — use add-contact-data-points with entityIds instead

Parameters

contacts (required)

Array of { contactName, companyIdentifier } objects.
  • contactName: First name, last name, or full name (e.g., “John”, “Smith”, or “John Smith”)
  • companyIdentifier: Domain or company LinkedIn URL (NOT person LinkedIn URLs)
    • Domains: “openai.com”, “stripe.com”
    • LinkedIn: “linkedin.com/company/openai”
    • Company names: Convert if confident (e.g., “Stripe” → “stripe.com”), otherwise ask user

dataPoints (optional)

Enrich contacts/companies when creating a NEW search. For existing searches, use add-contact-data-points or add-company-data-points instead.⚠️ CRITICAL: NEVER add data points unless the user EXPLICITLY asks for them. Enrichments cost credits. Only include data points when the user’s message specifically requests that data.
  • “Find engineers at Stripe” → NO data points
  • “Find engineers at Stripe and get their emails” → add Email (user explicitly asked)
  • “Tell me about OpenAI” → NO data points
  • Do NOT add Headcount Growth, Recent News, or any other data point “to be helpful” — only what the user asked for
Structure: { contactDataPoints?: DataPoint[], companyDataPoints?: DataPoint[] }DataPoint format:
  • Standard: { type: “<DataPointType>” }
  • Custom: { type: “Custom”, customDataPoint: “<brief description>” }
Important: Only include customDataPoint field when type is “Custom”Available contactDataPoints: Email, Summarize Work History, Find Thought LeadershipAvailable companyDataPoints: Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest FundingExamples:

Examples

Follow-ups

  • “Add [name] at [company] too” → Re-call with ALL contacts (previous + new)
  • “Actually look up [different people]” → Re-call with only the new contacts

Response Behavior

  • Summarize the search briefly (e.g., “Found 20 engineers at OpenAI”).
  • The tool returns a taskId for use with add-contact-data-points, add-company-data-points, custom functions, or get-task-context.
  • For emails, use add-contact-data-points with the taskId. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Input Parameters

object
Optional data points to enrich during search creation
array
required
Array of contact identifiers to find and enrich, with their company identifiers
Slug: CLAY_MCP_GET_CREDITS_AVAILABLECheck if credits are available for the workspace. Returns hasWorkspaceCredits, hasSalesRepCredits, and (when credit budgets are enabled) hasBudgetCredits.
Slug: CLAY_MCP_GET_CURRENT_WORKSPACEReport which Clay workspace this connection is pinned to. Returns workspaceName, workspaceId, and workspaceUrl. Use when the user asks which workspace they are connected to, or to confirm where searches and enrichments will run.
Slug: CLAY_MCP_GET_SUBROUTINE_INPUT_OPTIONSFetch the available dropdown options for a subroutine input that has a configured options source.

Input Parameters

string
required
The name of the input whose options to fetch.
string
required
The ID of the subroutine.
Slug: CLAY_MCP_GET_TASKGet task status and results by task ID. This tool handles all task types (search, direct) and returns the current state.

When to Use This Tool

This is a private tool used by the widget for polling task status.

Parameters

taskId (required)
  • The task ID to retrieve. Accepts:
    • Universal task IDs: mcp-task-* (from run_subroutine_direct, etc.)
    • Legacy search IDs: cgas-search-id-* (backwards compatible)
page (optional)
  • For direct tasks: 1-based page of entities (100 per page). Defaults to 1. The response includes totalEntities, hasMore, and overall completion status so callers don’t need every entity to know the task state. isComplete means every entity finished (completed or errored), not that all succeeded.

Input Parameters

integer
Optional 1-based page of entities for direct tasks (100 per page). Defaults to 1.
string
required
The task ID to retrieve (mcp-task-* or legacy cgas-search-id-*)
Slug: CLAY_MCP_GET_TASK_CONTEXTRetrieve the current state of a task — all entities, enrichment values, and statuses.

When to Use

Call this when you need the actual data behind an entity to answer the user’s question — e.g. the user asks “what’s John’s email?”, “what X profiles did you get?”, “show me the enrichment results”, or any question about data that may have been enriched. The initial response from search/data-points tools only includes base fields (name, title, company, LinkedIn); ALL enrichment values (emails, X/Twitter profiles, work history, custom data points) are only available through this tool.IMPORTANT: If the user asks about a data type and you don’t see it in the initial search response, that does NOT mean it wasn’t found — it means you need to call this tool to check.

Parameters

  • taskId (required): Task ID from a previous tool call. Accepts mcp-task-* IDs and legacy cgas-* search IDs.
  • entityIds (optional): Return only these entities.
  • page (optional): For direct tasks (run_subroutine_direct), a 1-based page of entities — up to 100 per page. Defaults to 1. Ignored when entityIds is provided.

Response

Returns entities and their enrichment values for the task. Each enrichment has a name, state (“completed” / “in-progress” / “error”), and value.Direct tasks are paginated: the response includes page, pageSize, totalEntities, and hasMore, plus processedEntities/isComplete for overall progress. isComplete means every entity finished (completed or errored), not that all succeeded. When hasMore is true, call again with the next page to retrieve more entities — or pass entityIds to fetch specific ones.

Input Parameters

integer
Optional 1-based page of entities for direct tasks (100 per page). Defaults to 1. Ignored when entityIds is provided.
string
required
The task ID to retrieve (mcp-task-* or legacy cgas-search-id-*)
array
Optional. Pass specific entity IDs to retrieve only those entities. Leave empty or omit to retrieve all entities for the task.
Slug: CLAY_MCP_LIST_SUBROUTINESList available functions. Available functions: Company Address, Company Industry, Company Employee Count, Company Domain, Company Job Openings, Company Revenue (Exact), Company Latest Funding, Enrich Person, Company News, Enrich Company, Find People at Company, Person Full Name, Person Job Title, Enrich Person and Find Contact Details, Person Location, Website Traffic, Website Technology Stack, Work Email. Call this to see their required inputs before using run_subroutine.
Slug: CLAY_MCP_QUERY_OBJECTSQuery audience accounts, contacts, or deals using natural language. This tool translates your description into a structured filter, validates it against the database, and returns matching entities with their field values.

Parameters

query (required)

Describe what you’re looking for in plain language. The tool automatically determines whether you’re querying accounts, contacts, or deals.

audienceName (optional, string)

Name of a saved audience segment to scope results to. The query filter is applied within this segment.

onlyMine (optional, boolean)

When true, restrict results to accounts owned by the calling user in Salesforce. Only applies when the query targets accounts.

limit (optional, default 50, max 100)

Max number of rows returned. Keep below 100 to stay LLM-context friendly.

offset (optional, default 0)

Pagination offset. Increment by limit to fetch additional pages.

Response

{ entityType, explanation, totalMatched, accounts | contacts }
  • entityType: The detected entity type (ACCOUNT or CONTACT)
  • explanation: Human-readable summary of the applied filter
  • totalMatched: Total entities matching the filter
  • Each entity carries its entityId, externalRecordId, and fields (keyed by display name) with values

Examples

Notes

  • No need to discover field IDs first — this tool handles field discovery internally
  • If the filter cannot be constructed from your description, a descriptive error is returned
  • For deep analysis of specific accounts (contacts, emails, calls), use ask-question-about-accounts with the account IDs from this tool’s results

Input Parameters

integer
Max rows to return
string
required
Natural language description of what to filter, e.g. “tech companies with 500+ employees”
integer
Pagination offset
boolean
When true, restrict account results to the caller’s Salesforce-owned accounts
string
Name of a saved audience segment to scope results to
Slug: CLAY_MCP_RUN_SUBROUTINEExecute a function on contacts/companies FROM AN EXISTING SEARCH (Company Address, Company Industry, Company Employee Count, Company Domain, Company Job Openings, Company Revenue (Exact), Company Latest Funding, Enrich Person, Company News, Enrich Company, Find People at Company, Person Full Name, Person Job Title, Enrich Person and Find Contact Details, Person Location, Website Traffic, Website Technology Stack, Work Email).

STOP! Choose the right tool:

  • User gave you specific values (LinkedIn URL, name, email)? → Use run_subroutine_direct instead!
  • User wants to run on contacts from a previous search? → Use THIS tool (run_subroutine)
  • Single contact: pass taskId + entityIds + fieldMapping
  • All contacts: pass taskId + fieldMapping

fieldMapping format

Format: { “entityField”: “subroutineInput” }
  • KEY = entity field name (from contact data, e.g. “name”, “url”, “domain”)
  • VALUE = subroutine input name (from list_subroutines, e.g. “full_name”, “linkedin_url”) Example: {“name”: “full_name”, “url”: “linkedin_url”, “domain”: “company_domain”}

IMPORTANT

Do NOT try to generate or summarize the function results yourself from your own knowledge. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Input Parameters

string
required
Required. The taskId from the existing search task to add results to.
array
Optional. Array of entityIds to run on. When omitted with fieldMapping, runs on all contacts.
object
Required for batch mode (running on ALL contacts). Format: { “entityField”: “subroutineInput” } — the KEY is the entity field name (from contact data), the VALUE is the subroutine input name. Example: if entity has “name” and subroutine needs “full_name”, use {“name”: “full_name”}. Either provide entityIds OR fieldMapping, not both.
string
required
The ID of the subroutine to execute. Get this from list_subroutines.
Slug: CLAY_MCP_RUN_SUBROUTINE_DIRECTExecute a custom function on one or more sets of provided inputs. NO existing task or entityIds needed.

When to Use This Tool

Use this tool when the user provides specific input values (like a LinkedIn URL, name, email, or a list of domains) and wants to run a function on that data directly. This is the PREFERRED tool when the user gives you concrete values to work with — for one value or many.

When NOT to Use This Tool

Do NOT use this tool if you need to run on contacts from an existing search. Use run_subroutine instead for batch operations on search results.

Usage

Provide:
  • subroutine_id: from list_subroutines
  • inputs: an ARRAY of input objects, one per run. Each object’s keys must match the input names from list_subroutines. Use a single-element array to run once. Example (one): [{“Linkedin URL”: “https://linkedin.com/in/someone”}] Example (many): [{“Domain”: “clay.com”}, {“Domain”: “google.com”}]

IMPORTANT

Each input set consumes credits (N sets = N runs). Do NOT try to generate or summarize the function results yourself from your own knowledge. Clay may render results in a widget in hosts that support MCP Apps, such as ChatGPT, claude.ai, and Cursor. Other terminal/coding-agent hosts such as Codex, Claude Code, Windsurf, and CLI environments do not show the widget. If you are unsure whether the widget is visible, assume it is not visible.
  • If a widget is visible, avoid repeating the full widget contents unless the user asks for full contents; then call get-task-context with the taskId and answer inline.
  • In terminal/coding-agent environments, when no widget is visible, or when the user asks for actual values/results, call get-task-context with the taskId and answer inline.
  • NEVER tell the user that data was not found, not returned, or unavailable without first calling get-task-context. The initial search/tool response only includes base fields — enrichment results (emails, X/Twitter profiles, work history, custom data points, etc.) are only available via get-task-context.
  • When the user asks about a specific value (e.g. “what’s Patrick’s email?”, “what X profiles did you get?”), call get-task-context FIRST to check if the data has already been enriched — the user may have triggered enrichments through the widget. Only call add-contact-data-points / add-company-data-points if get-task-context shows the enrichment hasn’t been run yet.
  • Use get-task-context to poll until async results complete; if values are still in-progress, wait and retry rather than answering with missing values.
  • If get-task-context is not available, fall back to get-task.

Response Behavior

Confirm briefly: “Running [function name]—results will appear shortly.”

Input Parameters

array
required
Array of input objects, one per run (max 1000); use a single-element array to run once. Each object’s keys must match the input names from list_subroutines. Example: [{“Linkedin URL”: “https://linkedin.com/in/john”}, {“Linkedin URL”: “https://linkedin.com/in/jane”}]
string
required
The ID of the subroutine to execute. Get this from list_subroutines.
Slug: CLAY_MCP_RUN_SUBROUTINE_NO_MAPPINGRun a custom subroutine on search entities. The backend automatically generates the field mapping.

Input Parameters

object
Optional. Explicit values for inputs the user selected (e.g. dropdown pickers), keyed by input name. Applied as-is; these override field mapping.
string
required
The taskId from the existing search.
array
Optional. Array of entityIds to run on. When omitted, runs on all entities.
string
required
The ID of the subroutine to execute.
Slug: CLAY_MCP_TRACK_EVENTTrack an analytics event with optional properties.

Input Parameters

string
required
The name of the event to track
object
Additional properties to include with the event