Connect HeyReach to ChatGPT: Automate LinkedIn Campaigns

If you need to connect HeyReach to ChatGPT to automate LinkedIn lead generation, manage multi-sender campaigns, or read and respond to LinkedIn inboxes, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and the HeyReach REST API.

If your team uses Claude, check out our guide on connecting HeyReach to Claude or explore our broader architectural overview on connecting HeyReach to AI Agents.

Giving a Large Language Model (LLM) read and write access to a LinkedIn automation platform like HeyReach requires navigating complex graph-based campaign structures, maintaining asynchronous proxy states for sender accounts, and handling strict rate limits. You can either build, host, and maintain this custom middleware yourself, or use a managed integration layer to dynamically generate a secure, authenticated MCP server URL.

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

The Engineering Reality of the HeyReach API

Building a custom MCP server is a self-hosted integration project. While the open MCP standard provides a predictable way for models to discover tools (tools/list) and execute them (tools/call), implementing it against HeyReach's specific API design presents immediate challenges for LLMs.

If you decide to build a custom MCP server for HeyReach, you own the entire API lifecycle. Here are the specific integration challenges you must solve:

Full Replacement Semantics (PUT/PATCH Quirks)

Many HeyReach endpoints, such as hey_reach_campaigns_update_settings, require full replacement of the object payload. This is a common but dangerous pattern when dealing with LLMs. If an LLM decides to only update a campaign's name and omits the exclusion fields (e.g., excludeAlreadyMessagedGlobal), the HeyReach API will reset the omitted fields to their defaults. Your custom MCP server must implement a read-before-write pattern to hydrate the payload, or you risk the LLM accidentally overwriting complex campaign settings.

Linked Node Trees for Campaign Sequences

The hey_reach_campaigns_update_sequence endpoint expects a fully formed workflow sequence represented as a linked node tree. Every path through the tree must terminate with an END node, and the JSON payload must perfectly map conditionalNode and unconditionalNode references alongside actionDelay metrics. Standard LLMs struggle immensely with generating strict, cyclic-graph-like JSON structures from scratch. If the schema isn't perfectly curated and injected with rigid instructions, the LLM will hallucinate invalid sequences and the API will reject the request.

Asynchronous Sender Account Lifecycles

HeyReach manages multiple LinkedIn accounts, which occasionally drop their connection due to LinkedIn's security mechanisms. Operations like hey_reach_linkedin_accounts_reconnect or hey_reach_linkedin_accounts_resync trigger immediately but process asynchronously. The API returns a 200 OK immediately, but the account is not actually ready. Your agent logic must know to poll hey_reach_linkedin_accounts_get_status to check if the state has settled, handle proxy configuration requirements, and potentially intercept PIN submission requests via hey_reach_linkedin_accounts_submit_pin.

Step 1: Generate a HeyReach MCP Server

Truto eliminates the need to build a custom MCP server by dynamically generating one based on your connected HeyReach account. This auto-generated endpoint handles the JSON-RPC wrapping, schema translation, and authentication routing automatically.

First, connect your HeyReach account via the Truto dashboard to generate an integrated_account_id.

You can create the MCP server using either the Truto UI or the API.

Method A: Via the Truto UI

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Click on your connected HeyReach account.
3. Open the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server (e.g., name it "HeyReach ChatGPT Server", select allowed HTTP methods, or filter by specific resource tags like campaigns or leads).
6. Click Save and copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API

For teams automating infrastructure, you can generate the MCP server programmatically. Make a POST request to the Truto API scoped to your integrated_account_id.

curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ChatGPT LinkedIn Ops Server",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["campaigns", "leads", "conversations"]
    }
  }'

The response will return the secure MCP endpoint:

{
  "id": "mcp-xyz-789",
  "name": "ChatGPT LinkedIn Ops Server",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

This URL handles all routing, authentication, and schema translation. Treat it like a highly privileged secret.

Step 2: Connect the MCP Server to ChatGPT

With the MCP server URL in hand, you must register it with your ChatGPT environment. You can do this via the desktop app UI or manually via an MCP configuration file.

Method A: Via the ChatGPT UI

1. Open the ChatGPT Desktop App.
2. Navigate to Settings -> Apps -> Advanced settings.
3. Enable Developer mode (MCP support requires this flag, available on Pro, Plus, Business, Enterprise, and Education accounts).
4. Under MCP servers / Custom connectors, click Add.
5. Enter a name (e.g., "HeyReach Automation").
6. Paste your Truto MCP URL into the Server URL field.
7. Click Save.

ChatGPT will immediately send an initialize request to the Truto MCP server, parsing the available HeyReach tools and making them accessible to your prompts.

Method B: Via Manual Config File

If you are using a local agent framework or managing ChatGPT connectors via a local file system architecture, you can register the server using the standard MCP configuration file (typically mcp.json).

Since Truto's MCP servers communicate over HTTP Server-Sent Events (SSE), you use the official MCP SSE transport command.

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

Restart your client, and it will immediately discover the HeyReach tools.

Hero Tools for HeyReach Automation

Truto exposes the full HeyReach API surface area as discrete tools. Here are the highest-leverage tools your AI agent can use to automate LinkedIn operations.

list_all_hey_reach_campaigns

Lists all HeyReach campaigns, returning critical metadata like status, progressStats, and exclusion rules. This is the primary discovery tool for agents trying to figure out what campaigns exist and their current health.

"Fetch a list of all active HeyReach campaigns. Filter for campaigns containing the keyword 'SDR' and output a markdown table showing the campaign name, status, and the number of leads processed from the progressStats."

create_a_hey_reach_campaign_lead

Adds leads to a specific HeyReach campaign. This tool supports bulk operations (up to 100 leads per request) and is vital for autonomous prospecting agents that scrape data and push it directly into an active campaign funnel.

"Take these 45 LinkedIn profile URLs we just scraped from the web, and add them as leads to the HeyReach campaign with ID 9481. Let me know how many were added successfully and if any failed validation."

hey_reach_conversations_send_message

Sends a direct message into an existing LinkedIn conversation (chatroom). This transforms ChatGPT into an active SDR, capable of drafting and sending contextual replies directly from the prompt window.

"Draft a polite, one-paragraph follow-up message to the prospect in conversation ID 59281 on account ID 112. Once drafted, use the send message tool to dispatch it immediately."

list_all_hey_reach_conversations

Retrieves the LinkedIn inbox for a specific sender account, returning conversation IDs, read statuses, and the full text of the last message sent. Useful for building an inbox triage agent.

"Fetch the latest unread conversations from HeyReach. Summarize the last message from each prospect, and highlight any that look like a positive reply or a request for a meeting."

hey_reach_campaigns_start

Activates a campaign from a DRAFT or PAUSED state. The agent must ensure a valid sequence and at least one connected LinkedIn sender account are attached before calling this tool.

"Check if campaign ID 4410 has a valid sequence attached. If it does, go ahead and activate the campaign using the start tool."

hey_reach_linkedin_accounts_get_status

Fetches the live connection status of a LinkedIn sender account. Essential for diagnosing failed campaigns or checking if an account requires PIN verification or proxy updates.

"Check the status of LinkedIn sender account ID 105. Tell me if the account is currently active, or if it requires a PIN submission or a session reconnect."

(To see the complete tool inventory and schema definitions, visit the HeyReach Integration Page.)

Workflows in Action

When you combine a frontier model like ChatGPT with Truto's auto-generated HeyReach MCP server, you can orchestrate complex LinkedIn operations entirely via conversational prompts.

Workflow 1: The Autonomous Inbox SDR

Managing replies across multiple LinkedIn sender accounts is tedious. You can instruct ChatGPT to act as an inbox triage agent that reads unread messages, drafts contextual replies, and sends them.

"Check all unread conversations in HeyReach. For any prospect who asks for pricing, draft a short reply mentioning that our base tier starts at $99/mo and ask if they have time for a 10-minute call next week. Send the replies automatically."

Execution Steps:

1. ChatGPT calls list_all_hey_reach_conversations with filters set to unread: true.
2. It parses the lastMessageText and lastMessageSender fields in the response.
3. For messages matching the intent ("pricing"), it drafts a context-aware response.
4. It loops through the target conversations and calls hey_reach_conversations_send_message with the drafted payload for each specific conversation_id.

Result: The user sees a summary of which prospects asked for pricing and confirmation that the follow-ups were successfully dispatched via the HeyReach API.

sequenceDiagram
  participant User as ChatGPT User
  participant GPT as ChatGPT Agent
  participant MCP as Truto MCP Server
  participant HR as HeyReach API

  User->>GPT: "Check unread, reply to pricing queries..."
  GPT->>MCP: tools/call list_all_hey_reach_conversations
  MCP->>HR: GET /conversations?unread=true
  HR-->>MCP: Array of Conversation Objects
  MCP-->>GPT: JSON-RPC Results
  GPT->>GPT: Analyze intents & draft replies
  GPT->>MCP: tools/call hey_reach_conversations_send_message
  MCP->>HR: POST /conversations/{id}/message
  HR-->>MCP: 200 OK
  MCP-->>GPT: Success Confirmation
  GPT-->>User: "I found 3 pricing requests and replied."

Workflow 2: Campaign Staging and Activation

Instead of clicking through the HeyReach UI to build a list and start a campaign, you can provide an agent with raw data and tell it to handle the staging and activation.

"I have a list of 50 LinkedIn URLs from a recent webinar. Add them to the draft campaign 'Q3 Webinar Follow-up'. Once the leads are added, check the campaign settings to ensure 'excludeAlreadyMessagedGlobal' is true. If everything looks good, activate the campaign."

Execution Steps:

1. ChatGPT parses the user's provided URLs.
2. It calls create_a_hey_reach_campaign_lead to inject the URLs into the specific campaign ID.
3. It calls get_single_hey_reach_campaign_by_id to inspect the excludeAlreadyMessagedGlobal flag.
4. It notices the flag is correct and proceeds to call hey_reach_campaigns_start to activate the campaign.

Result: The LLM handles bulk data entry, performs a pre-flight configuration check, and starts the campaign. The user receives a completion report with the number of leads successfully added and the new active status of the campaign.

Rate Limits and Error Handling

When automating LinkedIn operations via API, rate limits are a critical factor. HeyReach enforces rate limits to protect infrastructure and abide by upstream LinkedIn platform constraints.

When HeyReach returns an HTTP 429 Too Many Requests error, Truto explicitly passes this error directly back to the caller (ChatGPT). Truto does not intercept, throttle, or apply automatic backoff on rate limit errors. Instead, Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

It is the responsibility of the LLM or your agent framework to detect the 429 error, read the JSON-RPC error response, and decide whether to pause execution or alert the user. You can explicitly instruct ChatGPT in your system prompt: "If a tool returns an HTTP 429 error, halt execution immediately and tell me how many seconds remain before the reset."

Security and Access Control

Giving an LLM access to your LinkedIn outreach infrastructure requires strict guardrails. Truto's MCP architecture provides multiple layers of security at the token level, ensuring your agents only access what they need.

• Method Filtering: When generating the MCP server, you can restrict it using the methods array. For an analytics agent, setting methods: ["read"] ensures the LLM can only execute GET or LIST operations, physically preventing it from calling hey_reach_conversations_send_message or modifying campaigns.
• Tag Filtering: Use the tags array to isolate resources. An agent tasked with managing sender accounts only needs tags: ["linkedin_accounts"]. Truto will filter the tool list dynamically, hiding campaign and conversation tools entirely.
• Secondary Authentication: By enabling require_api_token_auth: true on the MCP server, the server URL alone is no longer enough to execute tools. The caller must also pass a valid Truto API token in the Authorization header, adding a required identity layer.
• Time-to-Live (TTL): Pass an expires_at ISO datetime when generating the MCP server to create temporary access tokens. Once the timestamp passes, the MCP server is permanently destroyed, making this ideal for short-lived, automated testing agents.

Automate LinkedIn Operations Without the Middleware

Connecting HeyReach to ChatGPT gives your SDR and marketing teams a powerful, natural language interface to orchestrate complex LinkedIn campaigns.

By leveraging Truto's SuperAI MCP Server, you bypass the painful process of building custom JSON-RPC middleware, parsing graph-based campaign schemas, and maintaining complex authentication lifecycles. Truto handles the API translation layer entirely, leaving you free to focus on designing high-leverage agent workflows.