Connect HeyReach to Claude: Manage Lead Lists and Outreach Performance

If you need to connect HeyReach to Claude to automate LinkedIn outreach campaigns, manage lead lists, or track multi-account sending performance, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function calls and HeyReach's REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on /connect-heyreach-to-chatgpt-automate-linkedin-campaigns-and-messaging/ or explore our broader architectural overview on /connect-heyreach-to-ai-agents-scale-linkedin-networking-and-workflows/.

Giving a Large Language Model (LLM) read and write access to a sprawling LinkedIn automation ecosystem like HeyReach is an engineering challenge. You have to handle API key lifecycles, map massive JSON schemas to MCP tool definitions, and deal with HeyReach's domain-specific data constraints. Every time HeyReach updates an endpoint or deprecates a legacy resource, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for HeyReach, connect it natively to Claude Desktop, and execute complex outreach management workflows using natural language.

The Engineering Reality of the HeyReach API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. HeyReach is built to manage massive LinkedIn outreach across dozens of sender accounts simultaneously. Its API reflects that complexity.

If you decide to build a custom HeyReach MCP server, here are the specific integration challenges you will face:

Asynchronous LinkedIn Account Synchronization HeyReach manages actual LinkedIn sessions, which means authenticating sender accounts involves proxies, PIN submissions, and multi-factor authentication states. Operations like reconnecting a LinkedIn account (hey_reach_linkedin_accounts_reconnect) or resyncing a profile trigger immediately but process asynchronously in the background. An LLM cannot simply wait for a synchronous success payload. Your MCP tools must be designed to initiate the action, and then separately poll status endpoints (hey_reach_linkedin_accounts_get_status) to determine if the account successfully connected or failed due to a proxy block.

Nested Workflow Sequences and Graph Dependencies Campaign creation in HeyReach is not a single CRUD operation. A campaign cannot be activated until it has a valid sequence (a node-based workflow tree), at least one assigned LinkedIn sender account, and an active schedule. If an LLM attempts to call hey_reach_campaigns_start on a bare campaign, the API will reject the request. Building an MCP server means enforcing these dependencies at the schema level, providing tools like hey_reach_campaigns_update_sequence that guide the LLM to structure a valid conditional node tree terminating with an END node before activation.

Flat Input Namespace vs. Complex Payloads When an MCP client calls a tool, all arguments arrive as a single flat object. HeyReach, however, relies heavily on complex, nested body parameters (like custom proxy configurations containing countryCode, host, port, username, password, and isCustomProxy flags). Your custom MCP router must manually map these flat arguments back into the deeply nested JSON shapes HeyReach expects. Truto's managed MCP architecture handles this dynamically, generating schemas from documentation and routing query parameters versus body parameters automatically on the fly.

Rate Limits and 429 Responses It is critical to understand how API limits are managed in an LLM context. HeyReach strictly rate limits API requests. When integrating via Truto, Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream HeyReach API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (your AI agent framework or Claude client) is strictly responsible for implementing retry and exponential backoff logic.

How to Generate a HeyReach MCP Server Using Truto

Truto's MCP architecture derives tool definitions dynamically from the integration's documented resources and schemas. Tools are not hard-coded - they are generated at runtime when Claude requests them, acting as a strict quality gate. If an endpoint lacks proper schema documentation, it is excluded from the server.

You can spin up an MCP server for a connected HeyReach account in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For teams who want a zero-code deployment, the Truto dashboard provides a direct path to generating an MCP URL.

1. Navigate to the Integrated Accounts page for your specific customer or tenant.
2. Select the connected HeyReach integration.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (name, allowed methods, resource tags, expiration date).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the REST API

For engineering teams embedding AI capabilities into their own products, MCP servers can be generated programmatically on the fly. This validates that tools are available, stores a securely hashed token in a distributed KV cache, and provisions the URL.

Make an authenticated POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/api/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HeyReach Campaign Manager Agent",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["campaigns", "leads", "linkedin_accounts"]
    }
  }'

The response contains the exact URL you will provide to Claude:

{
  "id": "mcp-789-xyz",
  "name": "HeyReach Campaign Manager Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["campaigns", "leads", "linkedin_accounts"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the HeyReach MCP Server to Claude

With your secure Truto MCP URL in hand, you can immediately map HeyReach tools to Claude. The URL encodes the specific tenant context and tool configurations - no further authentication or mapping is required by the end-user.

Method A: Via the Claude UI (Desktop or Web)

If you are using Claude's native application interfaces, adding a remote MCP server is a matter of pasting the URL.

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or Custom Connectors, depending on your tier).
2. Provide a recognizable name (e.g., "HeyReach Integration").
3. Paste the Truto MCP URL into the endpoint field.
4. Click Add or Save.

Claude will immediately call the tools/list protocol method, dynamically ingesting the HeyReach schemas, and the tools will become available in the conversation.

Method B: Via Manual Config File

If you are running Claude Desktop and prefer manual configuration, or if you are orchestrating an AI agent framework using LangChain or LlamaIndex, you can use the official SSE transport wrapper to point local configurations to Truto's remote endpoint.

Edit your claude_desktop_config.json file to include the server:

{
  "mcpServers": {
    "heyreach": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the connection via Server-Sent Events, discovering all exposed HeyReach proxy API methods.

HeyReach Hero Tools for Claude

Truto exposes a comprehensive suite of HeyReach operations as AI-ready tools. Below are the highest-leverage hero tools that enable complex outreach automation.

create_a_hey_reach_campaign

Creates a new HeyReach campaign in DRAFT status. This is the foundational step for any outreach flow. Note that a sequence must be added subsequently before the campaign can be activated.

"Claude, create a new HeyReach campaign named 'Q3 Enterprise Outreach'. Once created, let me know the Campaign ID so we can assign sender accounts to it."

hey_reach_campaigns_add_linkedin_accounts

Assigns LinkedIn sender accounts to an existing campaign. The HeyReach API allows up to 100 accounts per request, and individual failures do not fail the entire batch. This is critical for scaling outreach.

"Take the campaign ID we just created and assign these three LinkedIn account IDs to it as senders. Let me know if any of the assignments fail."

hey_reach_campaigns_update_sequence

Fully replaces the workflow sequence of a draft or paused campaign. This tool expects a complex node tree payload dictating delays, conditions, and actions, ensuring the AI can map out multi-step messaging logic.

"Update the sequence for the 'Q3 Enterprise Outreach' campaign. Build a simple node tree that sends a connection request, waits 2 days, and then sends a follow-up message if they accept."

list_all_hey_reach_campaign_stats

Retrieves campaign statistics grouped per campaign for a specific date range. This provides the LLM with aggregated metrics like connections sent, accepted, messages sent, and total replies.

"Pull the campaign stats for the last 14 days across all active campaigns. Tell me which campaign has the highest connection acceptance rate."

create_a_hey_reach_campaign_lead

Adds up to 100 leads to a specific HeyReach campaign in a single request. Leads can be identified by their LinkedIn URLs or member IDs.

"I have a list of 15 LinkedIn profile URLs in this document. Please add all of them as leads to the 'Q3 Enterprise Outreach' campaign."

hey_reach_conversations_send_message

Sends a direct message to an active LinkedIn conversation in HeyReach. This enables Claude to act as a triage agent, responding to prospects automatically based on conversational context.

"Check the recent unread conversations. For any prospect asking about pricing, send them a message summarizing our enterprise tiers and mark the conversation as seen."

To view the complete inventory of available tools, including webhooks, proxy management, and custom field operations, see the HeyReach integration page.

Workflows in Action

AI agents excel when chaining multiple discrete API calls into a cohesive outcome. Here are concrete examples of how Claude navigates the HeyReach API via Truto.

Scenario 1: Autonomous Campaign Provisioning

A growth marketer wants to spin up a new outreach campaign, assign specific LinkedIn accounts, define the automation logic, and set it live entirely through chat.

"Claude, create a new HeyReach campaign called 'Q4 Director Outreach'. Add LinkedIn sender account IDs acc_123 and acc_456 to it. Then, update the sequence to send a connection request, wait 3 days, and send a message. Finally, activate the campaign."

Step-by-step execution:

1. Claude calls create_a_hey_reach_campaign to generate the base campaign record and retrieves the campaignId.
2. Claude calls hey_reach_campaigns_add_linkedin_accounts using the new campaignId and the provided account IDs.
3. Claude calls hey_reach_campaigns_update_sequence passing a JSON representation of the node tree, ensuring all paths lead to an END node.
4. Claude calls hey_reach_campaigns_start to move the campaign from DRAFT to active.

Result: The marketer receives a confirmation that the campaign is live and actively queuing tasks for the assigned senders.

sequenceDiagram
    participant Claude as Claude Agent
    participant Truto as Truto MCP Server
    participant HeyReach as HeyReach API
    Claude->>Truto: Call create_a_hey_reach_campaign
    Truto->>HeyReach: POST /campaigns
    HeyReach-->>Truto: campaignId
    Truto-->>Claude: Returns campaignId
    Claude->>Truto: Call hey_reach_campaigns_update_sequence
    Truto->>HeyReach: PUT /campaigns/{id}/sequence
    HeyReach-->>Truto: 200 Success
    Truto-->>Claude: Sequence updated
    Claude->>Truto: Call hey_reach_campaigns_start
    Truto->>HeyReach: POST /campaigns/{id}/start
    HeyReach-->>Truto: 200 Success
    Truto-->>Claude: Campaign activated

Scenario 2: Lead Extraction and Triage

A sales operations manager wants to audit current outreach performance and actively manage a high-value list based on campaign data.

"Claude, pull the stats for the 'Founders List' campaign. Then, look at all the leads in that campaign. If any lead has a status of 'connected' but hasn't received a message yet, stop their progression in the campaign so I can follow up manually."

Step-by-step execution:

1. Claude calls list_all_hey_reach_campaign_stats filtering for the specific campaign to summarize the overall metrics.
2. Claude calls list_all_hey_reach_campaign_leads to retrieve the array of leads and their current statuses (leadConnectionStatus, leadMessageStatus).
3. Claude parses the returned JSON to identify leads that meet the criteria (connected, no message sent).
4. Claude iterates over the identified leads, calling hey_reach_campaign_leads_stop for each to pause their automation.

Result: The manager receives a high-level performance summary and a confirmed list of leads that have been successfully paused for manual intervention.

flowchart TD
    A["Claude Agent"]
    B["list_all_hey_reach_campaign_stats"]
    C["list_all_hey_reach_campaign_leads"]
    D["hey_reach_campaign_leads_stop"]
    A -->|"1. Fetch metrics"| B
    A -->|"2. Pull leads"| C
    C -->|"3. Filter status"| D
    D -->|"4. Pause lead"| A

Security and Access Control

Exposing an automation platform like HeyReach to an LLM requires strict boundary setting. Truto MCP servers provide built-in access controls to ensure the model cannot perform destructive actions unless explicitly permitted.

• Method Filtering: Restrict servers to specific operation types. Set config.methods: ["read"] to allow only get and list tools, preventing Claude from accidentally starting campaigns or deleting lists.
• Tag Filtering: Group tools by functional area. By setting config.tags: ["reporting"], the server will only expose analytics and stats endpoints, hiding the lead mutation tools.
• Additional Authentication (require_api_token_auth): For shared environments, toggle this flag to require the client to pass a valid Truto API token in the Authorization header alongside the MCP URL.
• Time-to-Live (expires_at): Generate short-lived MCP servers for contractors or temporary AI workflows. Once the ISO datetime is reached, distributed alarms automatically clean up the database records and KV cache, instantly revoking access.

Take AI Outreach to Production

Connecting Claude to HeyReach enables entirely new paradigms of autonomous outbound marketing and lead intelligence. However, writing and maintaining a custom MCP server to handle HeyReach's proxy structures, nested nodes, and async states is a massive drain on engineering resources.

By leveraging Truto's managed MCP architecture, you shift the burden of token lifecycle management, tool generation, and schema normalization off your team. You get a secure, dynamic URL that plugs directly into Claude or any MCP-compatible framework, letting you focus on building agentic workflows instead of parsing API documentation.