--- name: "firsttouch" description: "Manage FirstTouch Audiences, Flow Plans, outreach actions, tasks, enrichment, queues, metrics, and LinkedIn workflows through FirstTouch MCP." compatibility: "Requires an authenticated FirstTouch MCP connection and the permissions needed for each requested action." metadata: author: "FirstTouch" version: "1.1" --- # FirstTouch > FirstTouch helps teams build and run outbound workflows across Audiences, Flow Plans, email, LinkedIn, HubSpot, signals, tasks, enrichment, and AI-assisted workflow control through FirstTouch MCP. Use this file as an agent-facing guide for FirstTouch MCP. For HTTP integrations using the same operations, start with [Agent Start Here](https://docs.firsttouch.com/api-reference/agent-start.md) and the [HTTP quickstart](https://docs.firsttouch.com/api-reference/quickstart.md). Find exact tool names and direct Markdown references in the [operation catalog](https://docs.firsttouch.com/api-reference/operation-catalog.md). Use the [canonical OpenAPI document](https://gateway.firsttouch.ai/api/public/openapi.json) for current schemas, descriptions, and MCP annotations, and [execution and recovery](https://docs.firsttouch.com/api-reference/execution-and-recovery.md) for pending actions and retry handling. Do not invent missing output fields or assume HTTP success confirms completed outreach. For documentation navigation, see [llms.txt](https://docs.firsttouch.com/llms.txt). For user-facing MCP examples, see [FirstTouch MCP Prompt Library](https://docs.firsttouch.com/WebApp/Mcp/prompt-library.md). ## Prefer MCP For FirstTouch Workflows Use FirstTouch MCP when the user wants to manage outbound work from an AI assistant. FirstTouch MCP is team-scoped. Auth tokens belong to a specific FirstTouch Team, so always verify the current user and Team before taking action when the user may have access to multiple Teams. Recommended setup: ```bash claude mcp add firsttouch --transport http https://mcp.firsttouch.ai ``` If the MCP server URL differs for the user's Team, use the URL shown in FirstTouch settings or the MCP connection docs. Interactive MCP clients should normally use browser OAuth and team approval. Server integrations or MCP clients with secure custom-header support can instead send a Public API key as `X-API-Key`. The key belongs to its creator, is fixed to its creation team, and runs with that user's current permissions. Never ask a user to paste a real API key into a prompt. Direct them to store it in a secrets manager or the MCP client's secure header configuration. See [Public API authentication](/api-reference/authentication) and [MCP connection setup](/WebApp/Mcp/connect). ## Common Workflows ### 1. Create Audiences And Flow Plans Use this when the user describes recipients, lists, segments, filters, a HubSpot list, a Sales Navigator source, pasted contacts, or multiple contacts. Typical path: 1. Create or select an Audience. 2. Create or select a Flow Plan. 3. Attach the Audience to the Flow Plan. 4. Draft or update the flow actions. 5. Publish only after the user confirms. 6. Enroll awaiting contacts when the user is ready. Primary tools: - `list_audiences` - `create_audience` - `create_audience_from_profiles` - `attach_audience_to_flow` - `list_flow_plans` - `create_flow_plan` - `get_flow_workspace` - `update_flow_plan` - `replace_flow_root` - `manage_flow_publication` Important: - Ask whether the flow should use Manual Mode or Auto-Enrollment when the user has not specified it. - Publishing a Manual Mode flow does not enroll awaiting contacts by itself. - For complex flow/audience writes, present the exact plan and ask for confirmation before write tools. ### 2. Create Dynamic Actions For One Contact Use Dynamic Actions when the user asks to send, schedule, draft, approve, call, or follow up with one named person. Primary tools: - `get_guide` with `topic=dynamic_actions` - `find_contact_data` - `find_mcp_enrollment` - `add_dynamic_action` - `remove_dynamic_action_prospect` Basic properties for `add_dynamic_action`: - `contact`: verified identity and channel data, including first name, last name, and the required action target. - `contact.prospectId`: existing FirstTouch prospect id, when already known. - `contact.email`: target for email actions unless `action.recipientEmail` or the selected enrollment already has an email. - `contact.linkedInUrl`: target for LinkedIn actions unless the selected enrollment already has it. - `contact.phone`: target for call tasks unless the selected enrollment already has it. - `contact.firstName` and `contact.lastName`: pass both unless the selected prospect or enrollment already resolves to a full name. - `company.domain`: optional company identity and context. - `enrollmentId`: existing MCP Dynamic Actions enrollment to continue. - `ownerId`: default owner for the dynamic enrollment. - `action.assignedUserId`: sender/owner for the specific action. - `allowUnreadyLinkedInAccount`: only after the user explicitly accepts the risk of creating a LinkedIn action before the LinkedIn account is ready. Supported `action.type` values: - `email` - `linkedin_connect` - `linkedin_message` - `linkedin_profile_view` - `manual_task` - `call_task` Feature-gated Teams can also use `linkedin_inmail` when the assigned LinkedIn account and plan are eligible. Important: - A prospect id is not required when the user supplies both names and the required exact action target, such as email, LinkedIn URL, or phone. - Before adding an action, load the Dynamic Actions guide. Call `find_contact_data` with every known identity unless verified enrichment was returned earlier in the conversation, then call `find_mcp_enrollment`. If enrollment candidates exist, ask whether to continue one or start a new sequence. Resolve and pass `action.assignedUserId` using `get_current_user` and `list_team_members`. - Dynamic Actions do not enrich internally. `find_contact_data` reads existing data as part of preflight; charged enrichment is a separate action. Ask for missing first or last names instead of automatically enriching. - Dynamic Action creation and removal require Team Admin authority and an active paid plan or trial. - Customer-supplied exact targets are authoritative. If lookup/enrichment returns a different email, LinkedIn URL, or phone, ask which value to use. - Email, LinkedIn, and call actions default to no human approval. Set `action.isHumanApprovalRequired=true` only when the user asks for review or approval. - Write final message content in the MCP client. Do not rely on FirstTouch AI generation for Dynamic Actions. - Use variables like `{ft.flow.prospect_first_name}` only when the matching field is known and passed, or when the selected enrollment is known to have it. - Call `add_dynamic_action` once per step in a multi-step one-contact sequence. Use the returned `enrollmentId` for follow-up steps. Retain `enrollmentId` plus `nodeId` as the write receipt; if `nodeAppended=true`, do not repeat that step because task IDs are empty or tasks are still being created. - Use `action.appendTarget=connection_accepted` or `action.appendTarget=connection_timeout` only for LinkedIn connection branch follow-ups. - Never mutate the returned MCP Dynamic Actions `flowPlanId` with normal flow-plan mutation tools. ### 3. Monitor LinkedIn Signals Use LinkedIn Signals when the user wants FirstTouch to monitor LinkedIn profile post likes/comments, capture engagers, and route those people into the linked Social Engagement flow. Primary tools: - `get_social_engagement_config` - `manage_social_engagement_monitored_profile` - `write_social_engagement_config` - `list_social_engagement_monitored_profiles` - `list_social_engagement_engagers` Basic properties: - `linkedinUrl`: LinkedIn profile URL to monitor. - `loadHistory`: load recent available engagement history when adding a profile. - `enableSocialEngagement`: start collection while adding the profile. - `profileId`: monitored profile id for activate, deactivate, or delete. - `isEnabled`: enable or disable Social Engagement for the current team. Important: - For "monitor this profile and send outreach to people who engaged" requests, call `manage_social_engagement_monitored_profile` with `action=add` first. - Use `response.socialEngagement.flowPlan.id` as the existing linked Social Engagement flow. Do not create a separate Social Engagement flow. - Collection can start before the linked flow is published, but captured engagers enter the flow only after the linked flow is published and valid. - Adding or activating monitored profiles requires paid, non-trial Social Engagement access and Team Admin permissions. ### 4. Discover And Enrich Contacts Use discovery when the user wants to find new prospects by filters. Use lookup/enrichment when the user needs known or missing contact data for a specific person. Primary tools: - `get_guide` with `topic=contact_discovery` - `get_contact_discovery_industry_values` - `discover_contacts` - `start_contact_discovery_audience_import` - `get_contact_discovery_audience_import_status` - `find_contact_data` - `enrich_email` - `enrich_phone` - `enrich_contact` - `enrich_company` Basic discovery properties: - `pageSize`: number of profiles to return; use `1` for a preview. - role/title filters. - location filters. - company name or bare company domain. - company size, industry, funding, founded year, and company type filters. - exclusion filters for locations, titles, industries, company names, headlines, and summaries. Important: - Contact discovery uses FirstTouch credits. Preview with `pageSize=1` when practical. - `discover_contacts` reserves `pageSize` credits and charges one FirstTouch credit per returned profile row. - `start_contact_discovery_audience_import` can fetch up to 100 total profiles asynchronously and requires confirmed max credits for additional rows. - Use two-letter Alpha-2 country codes and bare company domains. - Use `current_company_primary_industry` for strict company industry filters. - `find_contact_data` is free and reads existing team data only; it does not enrich, spend credits, or create enrollments. - Charged enrichment results are returned to the caller only. They do not automatically update enrollments, Awaiting candidates, Audience Contacts, saved prospects, or HubSpot records; use a separate supported write action when the user asks to apply a result. ### 5. Track Outreach Queues Use queue tools when the user asks what is waiting, blocked, scheduled, sent, failed, canceled, or why an action has not run. Primary tools: - `list_linkedin_outreach_queue` - `list_email_send_queue` - `get_flow_enrollment` - `list_enrollments` - `list_user_tasks` LinkedIn queue views: - `active`: current/waiting LinkedIn actions; excludes terminal history. - `review_required`: pre-provider-request actions blocked by requirements. - `in_queue`: provider requests still pending. - `done`, `failed`, `canceled`: terminal provider request history. - `all`: normal outreach rows across statuses. - `diagnostic_all`: expanded debug view across internal request types. Email queue views: - `in_queue`: submitted email sends waiting to run. - `awaiting`: submitted email sends awaiting execution. - `done`, `failed`, `canceled`: terminal submitted sends. Important: - LinkedIn queue tools read FirstTouch queue state only; they do not query external providers live. - Email queue results only include email actions after they were submitted to the email sending service and received an estimated send time. - If an expected email is missing from `list_email_send_queue`, inspect the enrollment and tasks; it may be blocked before enqueue by approval, sender setup, missing email, or a future flow step. ### 6. Measure Team Performance Use team metrics when the user asks for performance, sent actions, engagement, replies, sentiment, opportunities, meetings booked, or chart trends. Primary tools: - `get_team_metrics` - `list_flow_plans` Basic properties: - `fromUtc`, `toUtc`: UTC date range. - `flowPlanIds`: source/flow filters. - `userIds`: sender/team member filters. - `includeTotals` - `includeActions` - `includeEngagement` - `includeOpportunities` - `includeEmailChart` - `includeLinkedinChart` Important: - Request chart fields only when the user asks for trends, charts, or date buckets. - Date filters are interpreted as whole UTC days. - Team owners can omit `userIds` for all accessible team users; non-owners are scoped by the service. - Use `list_flow_plans` with metrics/order filters when ranking or comparing individual flows. ### 7. Find Team LinkedIn Connections Use this when the user asks who on the team is connected to a person, or wants to inspect saved LinkedIn connections for a team member. Primary tool: - `list_linkedin_team_connections` Basic properties: - `mode`: `auto`, `connections_of_team_member`, or `team_members_connected_to_person`. - `ownerUserId` - `ownerSearch` - `linAccountId` - `connectedPersonLinkedInUrl` - `connectedPersonPublicIdentifier` - `connectedPersonName` - `searchQuery` Important: - This reads saved FirstTouch connection data only. It does not query external providers live. - Use this before assigning LinkedIn outreach when a warm sender may exist. ### 8. Review And Complete Tasks Use task tools when the user wants to review approval tasks, edit generated content, complete manual work, approve outreach, or skip tasks. Primary tools: - `list_user_tasks` - `preview_task` - `edit_task_action` - `complete_task` - `skip_task` Important: - Preview human approval tasks before completing them. - Complete or skip tasks only after the user explicitly asks. - For approvals created by Dynamic Actions, offer task links and explain whether execution is waiting on approval. ### 9. HubSpot Lists And Enrollment Use HubSpot list tools when the user wants to use a HubSpot list as a FirstTouch audience source. Primary tools: - `list_hubspot_lists` - `preview_hubspot_list` - `create_audience` - `attach_audience_to_flow` Use enrollment tools when the user wants to inspect, start, cancel, validate, or retry flow enrollments. Primary tools: - `list_flow_plan_enrollments` - `list_enrollments` - `get_flow_enrollment` - `add_manual_flow_enrollment` - `enroll_awaiting_flow_items` - `validate_flow_reenroll` - `reenroll_flow_enrollments` - `cancel_flow_enrollments` ## Safety And Permissions - FirstTouch MCP follows the current user's FirstTouch team permissions. - Use `get_current_user`, `get_auth_scopes`, `get_credits_usage`, and `get_feature_costs` before writes or charged actions when context is unclear. - Team owner/admin permissions are required for many flow, audience, Social Engagement, and team-wide operations. - Charged discovery and enrichment use FirstTouch credits, not USD. Show credit impact and ask for confirmation before larger charged actions. - Do not publish flows, enroll contacts, complete approvals, start Social Engagement, or run charged enrichment unless the user has clearly asked or confirmed. - For single-contact action requests, prefer Dynamic Actions over creating an Audience or reusable Flow Plan. - For multi-contact or segment requests, use Audience and Flow Plan workflows instead of one Dynamic Action per contact. - Preserve the user's exact supplied email, LinkedIn URL, or phone unless they confirm a different value from lookup/enrichment. ## Useful User Prompts ```text Show my current FirstTouch user, team, permissions, and credit balance. ``` ```text Preview VP Sales prospects in US SaaS companies before spending more discovery credits. ``` ```text Create an Audience from these contacts, attach it to a draft Flow Plan, and show validation before publishing. ``` ```text Prepare a follow-up email to Brittany Chen at brittany@example.com with human approval required. Use my connected email account and show me the content before sending. ``` ```text Monitor this LinkedIn profile, load recent engagement history, and route people who like or comment into the linked Social Engagement flow. ``` ```text Show active LinkedIn outreach waiting to run and explain anything blocked. ``` ```text Show submitted email sends for this flow and tell me why expected emails have not sent. ``` ```text Show email and LinkedIn engagement, positive replies, and meetings booked for the last 30 days. Include daily chart trends. ``` ```text Who on our team is connected to this LinkedIn profile? ``` ## Reference - [FirstTouch MCP Overview](/WebApp/Mcp/overview) - [Connect FirstTouch MCP](/WebApp/Mcp/connect) - [FirstTouch MCP Use Cases](/WebApp/Mcp/use-cases) - [FirstTouch MCP Prompt Library](/WebApp/Mcp/prompt-library) - [FirstTouch MCP Troubleshooting](/WebApp/Mcp/troubleshooting)