# How to connect Clay MCP to Claude Cowork

```json
{
  "title": "How to connect Clay MCP to Claude Cowork",
  "toolkit": "Clay MCP",
  "toolkit_slug": "clay_mcp",
  "framework": "Claude Cowork",
  "framework_slug": "claude-cowork",
  "url": "https://composio.dev/toolkits/clay_mcp/framework/claude-cowork",
  "markdown_url": "https://composio.dev/toolkits/clay_mcp/framework/claude-cowork.md",
  "updated_at": "2026-09-03T05:36:11.814Z"
}
```

## Introduction

Cowork is Anthropic's AI agent for knowledge work. Think of it as Claude Code for everything else. It works autonomously with your computer, local files, and applications to accomplish complex tasks.
This guide walks you through the easiest and most secure way to connect your Clay account to Cowork via Composio Connect, enabling it to find enriched contacts for Acme Corp, enrich leads and retrieve emails and titles, run enrichment providers for startup lists, and more such actions on your behalf without compromising your account security.

## Also integrate Clay MCP with

- [ChatGPT Work](https://composio.dev/toolkits/clay_mcp/framework/chatgpt)
- [Hermes](https://composio.dev/toolkits/clay_mcp/framework/hermes-agent)

## Connect Clay MCP to Claude Cowork

### Connecting Clay to Claude Cowork
1. Open Customize
In Claude Desktop, click Customize in the left sidebar, then select Connectors and click the + icon at the top.
2. Add the Composio MCP server
Click Add custom connector and paste in the Composio MCP server URL:

```bash
https://connect.composio.dev/mcp
```

## What is Claude Cowork?

Claude Cowork is Anthropic's agent for general knowledge work. It can use your computer, files, and connected applications to complete longer-running tasks across your work tools.
With Composio Connect, Cowork can securely access apps like Clay through MCP without you sharing account credentials directly with the agent.

## What is the Clay MCP server, and what's possible with it?

The Clay MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Clay account. It provides structured and secure access so your agent can perform Clay operations on your behalf.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `CLAY_MCP_ADD_COMPANY_DATA_POINTS` | Add-company-data-points | Add 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: "" } - Custom: { type: "Custom", customDataPoint: "" } **Available standard types:** Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding **Custom 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 \| User request \| dataPoints \| \|--------------\|------------\| \| "What's their tech stack?" \| [{ type: "Tech Stack" }] \| \| "Get funding info and headcount" \| [{ type: "Latest Funding" }, { type: "Headcount" }] \| \| "Find recent product announcements" \| [{ type: "Custom", customDataPoint: "recent product announcements" }] \| \| "Are they B2B or B2C?" \| [{ type: "Custom", customDataPoint: "B2B vs B2C classification" }] \| \| "What's in the news about them?" \| [{ type: "Custom", customDataPoint: "recent news and headlines" }] \| ## 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. |
| `CLAY_MCP_ADD_CONTACT_DATA_POINTS` | Add-contact-data-points | Add 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: "" } - Custom: { type: "Custom", customDataPoint: "" } **Available standard types:** Email, Summarize Work History, Find Thought Leadership **Custom 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 \| User request \| dataPoints \| \|--------------\|------------\| \| "Get their emails" \| [{ type: "Email" }] \| \| "Add work history" \| [{ type: "Summarize Work History" }] \| \| "Find their recent publications" \| [{ type: "Custom", customDataPoint: "recent publications" }] \| \| "What's their LinkedIn activity?" \| [{ type: "Custom", customDataPoint: "recent LinkedIn posts" }] \| \| "Score them for senior leaders in NYC" \| [{ type: "Custom", customDataPoint: "ICP fit: senior leader in NYC" }] \| \| "Get John's email" (single contact) \| [{ type: "Email" }] + entityIds: [""] \| ## 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. |
| `CLAY_MCP_ASK_QUESTION_ABOUT_ACCOUNTS` | Ask-question-about-accounts | Ask 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 \| User says \| How to handle \| \|-----------\|---------------\| \| "What's happening with the Acme deal?" \| 1. Call `query-objects` with query: "Acme account" to get the account entityId. 2. Call this tool with that entityId in accountIds and the question. \| \| "What's happening with my Acme deal?" \| 1. Call `query-objects` with query: "Acme account" and onlyMine: true to get the account entityId. 2. If Clay says owner-scoped filtering is unavailable, explain that Clay can still search audience accounts but cannot determine ownership in this workspace. 3. Otherwise call this tool with that entityId in accountIds and the question. \| \| "Compare my top two accounts" \| 1. Call `query-objects` with query: "my accounts" and onlyMine: true to find accounts. 2. If owner-scoped filtering is unavailable, explain that Clay can still analyze audience accounts but cannot determine ownership in this workspace. 3. Otherwise call this tool with both entityIds in accountIds and the question. The tool returns individual analyses per account; synthesize and compare the results yourself. \| \| "Who are the key contacts at account 12345?" \| Call this tool directly with accountIds: [12345] and question: "Who are the key contacts?" (ID already known). \| ## 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 |
| `CLAY_MCP_FIND_AND_ENRICH_COMPANY` | Find-and-enrich-company | Find 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: "" } - Custom: { type: "Custom", customDataPoint: "" } **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 \| User request \| Parameters \| \|--------------\|------------\| \| "Tell me about Stripe" \| companyIdentifier: "stripe.com" (NO companyDataPoints — user did not ask for enrichments) \| \| "What's OpenAI's funding?" \| companyIdentifier: "openai.com", companyDataPoints: [{ type: "Latest Funding" }] \| \| "Canva's competitors and tech stack" \| companyIdentifier: "canva.com", companyDataPoints: [{ type: "Company Competitors" }, { type: "Tech Stack" }] \| \| "Notion's product roadmap" \| companyIdentifier: "notion.so", companyDataPoints: [{ type: "Custom", customDataPoint: "product roadmap" }] \| ## 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. |
| `CLAY_MCP_FIND_AND_ENRICH_CONTACTS_AT_COMPANY` | Find-and-enrich-contacts-at-company | Search 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:** \| Filter \| Type \| Description \| \|--------\|------\|-------------\| \| names \| string[] \| Search by name — can be first name, last name, or full name (e.g., ["Smith"], ["John Smith"]) \| \| job_title_keywords \| string[] \| Titles to include \| \| job_title_exclude_keywords \| string[] \| Titles to exclude (e.g., ["Intern"]) \| \| profile_keywords \| string[] \| Keywords anywhere in the LinkedIn profile (headline, about, experience, etc.). Use for broad keyword searches, e.g. ["AI", "machine learning"] or ["founder", "co-founder"] \| \| certification_keywords \| string[] \| Certifications (e.g., ["AWS", "CPA"]) \| \| languages \| string[] \| Profile languages \| \| school_names \| string[] \| Schools attended \| \| current_role_min_months_since_start_date \| number \| Min months in role (tenured) \| \| current_role_max_months_since_start_date \| number \| Max months in role (new hires) \| \| locations \| string[] \| Locations to include (use formal names: "United States", "California") \| \| locations_exclude \| string[] \| Locations to exclude \| ### 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: "" } - Custom: { type: "Custom", customDataPoint: "" } **Important:** Only include `customDataPoint` field when type is "Custom" **Available contactDataPoints:** Email, Summarize Work History, Find Thought Leadership **Available companyDataPoints:** Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding **Examples:** \| User request \| dataPoints \| \|--------------\|------------\| \| "engineers at Stripe" \| NONE — user did not ask for enrichments \| \| "engineers at Stripe with emails" \| { contactDataPoints: [{type: "Email"}] } \| \| "Canva's competitors and funding" \| { companyDataPoints: [{type: "Company Competitors"}, {type: "Latest Funding"}] } \| \| "VPs at Figma with emails + company tech stack" \| { contactDataPoints: [{type: "Email"}], companyDataPoints: [{type: "Tech Stack"}] } \| \| "Notion's product roadmap" (custom) \| { companyDataPoints: [{type: "Custom", customDataPoint: "product roadmap"}] } \| ## Examples \| User says \| Parameters \| \|-----------\|------------\| \| "Find people at OpenAI" \| companyIdentifier: "openai.com" \| \| "VP Finance at HubSpot" \| companyIdentifier: "hubspot.com", contactFilters: { job_title_keywords: ["VP Finance"] } \| \| "VPs and Directors in California at HubSpot" \| companyIdentifier: "hubspot.com", contactFilters: { job_title_keywords: ["VP", "Director"], locations: ["California"] } \| \| "Marketing managers outside the US at Salesforce" \| companyIdentifier: "salesforce.com", contactFilters: { job_title_keywords: ["Marketing Manager"], locations_exclude: ["United States"] } \| \| "New hires at Stripe (last 3 months)" \| companyIdentifier: "stripe.com", contactFilters: { current_role_max_months_since_start_date: 3 } \| \| "Find people mentioning AI at OpenAI" \| companyIdentifier: "openai.com", contactFilters: { profile_keywords: ["AI", "artificial intelligence", "machine learning"] } \| \| "Find founders at YC companies" \| companyIdentifier: "ycombinator.com", contactFilters: { profile_keywords: ["founder", "co-founder"] } \| \| "Find someone named Urmanov at Allstate" \| companyIdentifier: "allstate.com", contactFilters: { names: ["Urmanov"] } \| ## 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 |
| `CLAY_MCP_FIND_AND_ENRICH_LIST_OF_CONTACTS` | Find-and-enrich-list-of-contacts | Find 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: "" } - Custom: { type: "Custom", customDataPoint: "" } **Important:** Only include `customDataPoint` field when type is "Custom" **Available contactDataPoints:** Email, Summarize Work History, Find Thought Leadership **Available companyDataPoints:** Headcount Growth, Recent News, Investors, Company Competitors, Company Customers, Tech Stack, Website Traffic, Open Jobs, Revenue Model, Annual Revenue, Latest Funding **Examples:** \| User request \| dataPoints \| \|--------------\|------------\| \| "engineers at Stripe" \| NONE — user did not ask for enrichments \| \| "engineers at Stripe with emails" \| { contactDataPoints: [{type: "Email"}] } \| \| "Canva's competitors and funding" \| { companyDataPoints: [{type: "Company Competitors"}, {type: "Latest Funding"}] } \| \| "VPs at Figma with emails + company tech stack" \| { contactDataPoints: [{type: "Email"}], companyDataPoints: [{type: "Tech Stack"}] } \| \| "Notion's product roadmap" (custom) \| { companyDataPoints: [{type: "Custom", customDataPoint: "product roadmap"}] } \| ## Examples \| User request \| contacts \| \|--------------\|----------\| \| "Find John Smith at OpenAI" \| [{ contactName: "John Smith", companyIdentifier: "openai.com" }] \| \| "Look up Jane Doe at Stripe and Bob Lee at Figma" \| [{ contactName: "Jane Doe", companyIdentifier: "stripe.com" }, { contactName: "Bob Lee", companyIdentifier: "figma.com" }] \| ## 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. |
| `CLAY_MCP_GET_CREDITS_AVAILABLE` | Get-credits-available | Check if credits are available for the workspace. Returns hasWorkspaceCredits, hasSalesRepCredits, and (when credit budgets are enabled) hasBudgetCredits. |
| `CLAY_MCP_GET_CURRENT_WORKSPACE` | Get-current-workspace | Report 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. |
| `CLAY_MCP_GET_SUBROUTINE_INPUT_OPTIONS` | Get subroutine input options | Fetch the available dropdown options for a subroutine input that has a configured options source. |
| `CLAY_MCP_GET_TASK` | Get-task | Get 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. |
| `CLAY_MCP_GET_TASK_CONTEXT` | Get-task-context | Retrieve 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. |
| `CLAY_MCP_LIST_SUBROUTINES` | List subroutines | List 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. |
| `CLAY_MCP_QUERY_OBJECTS` | Query-objects | Query 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 \| User says \| query parameter \| \|-----------\|----------------\| \| "Show me my healthcare accounts" \| "healthcare accounts" (+ onlyMine: true) \| \| "Find contacts whose title is VP Engineering" \| "contacts with title VP Engineering" \| \| "Accounts with open opportunities over $100k" \| "accounts with opportunities over $100k" \| \| "VPs at tech companies with 500+ employees" \| "VPs at tech companies with 500+ employees" \| \| "Healthcare accounts in my Enterprise Target list" \| "healthcare accounts" (+ audienceName: "Enterprise Target") \| ## 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 |
| `CLAY_MCP_RUN_SUBROUTINE` | Run subroutine | Execute 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) ## Usage (only if you have a taskId from a previous search) - 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. |
| `CLAY_MCP_RUN_SUBROUTINE_DIRECT` | Run subroutine direct | Execute 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." |
| `CLAY_MCP_RUN_SUBROUTINE_NO_MAPPING` | Run subroutine no mapping | Run a custom subroutine on search entities. The backend automatically generates the field mapping. |
| `CLAY_MCP_TRACK_EVENT` | Track-event | Track an analytics event with optional properties. |

## Supported Triggers

None listed.

## Creating MCP Server - Stand-alone vs Composio SDK

The Clay MCP server connects Claude Cowork to your Clay account through Composio. Once connected, Cowork can use the available Clay tools and triggers to complete tasks on your behalf.

## Complete Code

None listed.

## How to build Clay MCP Agent with another framework

- [ChatGPT Work](https://composio.dev/toolkits/clay_mcp/framework/chatgpt)
- [Hermes](https://composio.dev/toolkits/clay_mcp/framework/hermes-agent)

## Related Toolkits

- [HubSpot](https://composio.dev/toolkits/hubspot) - HubSpot is an all-in-one marketing, sales, and customer service platform. It lets teams nurture leads, automate outreach, and track every customer interaction in one place.
- [Pipedrive](https://composio.dev/toolkits/pipedrive) - Pipedrive is a sales management platform offering pipeline visualization, lead tracking, and workflow automation. It helps sales teams keep deals moving forward efficiently and never miss a follow-up.
- [Salesforce](https://composio.dev/toolkits/salesforce) - Salesforce is a leading CRM platform that helps businesses manage sales, service, and marketing. It centralizes customer data, enabling teams to drive growth and build strong relationships.
- [Apollo](https://composio.dev/toolkits/apollo) - Apollo is a CRM and lead generation platform that helps businesses discover contacts and manage sales pipelines. Use it to streamline customer outreach and track your deals from one place.
- [Attio](https://composio.dev/toolkits/attio) - Attio is a customizable CRM and workspace for managing your team's relationships and workflows. It helps teams organize contacts, automate tasks, and collaborate more efficiently.
- [Acculynx](https://composio.dev/toolkits/acculynx) - AccuLynx is a cloud-based roofing business management software for contractors. It streamlines project tracking, lead management, and document sharing.
- [Addressfinder](https://composio.dev/toolkits/addressfinder) - Addressfinder is a data quality platform for verifying addresses, emails, and phone numbers. It helps you ensure accurate customer and contact data every time.
- [Affinity](https://composio.dev/toolkits/affinity) - Affinity is a relationship intelligence CRM that helps private capital investors find, manage, and close more deals. It streamlines deal flow and surfaces key connections to help you win opportunities.
- [Agencyzoom](https://composio.dev/toolkits/agencyzoom) - AgencyZoom is a sales and performance platform built for P&C insurance agencies. It helps agents boost sales, retain clients, and analyze producer results in one place.
- [Agile CRM](https://composio.dev/toolkits/agile_crm) - Agile CRM is a unified customer management platform combining contacts, sales pipelines, marketing, and support. Use it to centralize customer data, automate campaigns, and manage deals and tickets in one place.
- [Bettercontact](https://composio.dev/toolkits/bettercontact) - Bettercontact is a smart contact enrichment tool for finding emails and phone numbers. It helps boost lead generation with automated, waterfall search across multiple sources.
- [Blackbaud](https://composio.dev/toolkits/blackbaud) - Blackbaud provides cloud-based software for nonprofits, schools, and healthcare institutions. It streamlines fundraising, donor management, and mission-driven operations.
- [Brilliant directories](https://composio.dev/toolkits/brilliant_directories) - Brilliant Directories is an all-in-one platform for building and managing online membership communities and business directories. It streamlines listings, member management, and engagement tools into a single, easy interface.
- [Capsule crm](https://composio.dev/toolkits/capsule_crm) - Capsule CRM is a user-friendly CRM platform for managing contacts and sales pipelines. It helps businesses organize relationships and streamline their sales process efficiently.
- [Centralstationcrm](https://composio.dev/toolkits/centralstationcrm) - CentralStationCRM is an easy-to-use CRM software focused on collaboration and long-term customer relationships. It helps teams manage contacts, deals, and communications all in one place.
- [Clientary](https://composio.dev/toolkits/clientary) - Clientary is a platform for managing clients, invoices, projects, proposals, and more. It streamlines client work and saves you serious admin time.
- [Close](https://composio.dev/toolkits/close) - Close is a CRM platform built for sales teams, combining calling, email automation, and predictive dialers. It streamlines sales workflows and boosts productivity with all-in-one communication tools.
- [Close MCP](https://composio.dev/toolkits/close_mcp) - Close MCP is a CRM MCP exposing leads, contacts, opportunities, activities, communications, and workflows. Use it to give agents scoped, auditable access to your CRM data.
- [Contacts+](https://composio.dev/toolkits/contacts_plus) - Contacts+ is a contact management service for personal account, contact, and tag data. It helps keep address books organized, searchable, and easier to maintain across workflows.
- [Dropcontact](https://composio.dev/toolkits/dropcontact) - Dropcontact is a B2B email finder and data enrichment service for professionals. It delivers verified email addresses and enriches contact info with up-to-date data.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and Clay MCP?

With a standalone Clay MCP server, the agents and LLMs can only access a fixed set of Clay tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Clay and many other apps based on the task at hand, all through a single MCP endpoint.

### Can I use Tool Router MCP with Claude Cowork?

Yes, you can. Claude Cowork fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Clay tools.

### Can I manage the permissions and scopes for Clay while using Tool Router?

Yes, absolutely. You can configure which Clay scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

### How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Clay data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)