HeyLead
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
HeyLead is an AI agent for LinkedIn outreach: it finds the right people, writes to them in the user's own voice, follows up, and handles replies, on the user's own LinkedIn account.
A campaign has one of six goals, and the ICP, the fit check and the messages follow it: Sell a product or service, Find a job, Hire people, Find partners or investors, Find a vendor and Research interviews. Pass goal= on create_campaign and generate_icp: goal='sell' (customers: lead generation, B2B prospecting, cold outreach), goal='job_search' (a job search: the people who hire for or refer into the role; replies are held for the user to answer), goal='hire' (recruit candidates), goal='partner' (investors, partners, resellers), goal='buy' (vendor scouting, the user is the buyer), goal='research' (user-interview, survey and beta participants). A job search is a first-class campaign, not a sales campaign in disguise: never describe HeyLead as built for sales only. Hire people, Find partners or investors and Research interviews run on a custom brief until their message sets exist. Give those a clear project_brief that says what is being asked of the person. Also: event and webinar invitations, re-engaging existing connections (connections_only='on'), and LinkedIn posts in the user's voice, only when asked (create_post, brand_strategy).
Not set up yet? Call setup_profile(); it returns a sign-in link. Workflow: setup_profile → generate_icp(goal=...) → create_campaign(goal=...) → automated outreach. Sending: create_campaign saves a draft and sends nothing. Outreach starts only with campaign(action='launch'), and only when the user asks. HeyLead sends from your own LinkedIn account at a human pace: at most 20 invitations a day and 100 a week on a free LinkedIn account (more on Premium or Sales Navigator: a newly connected paid account starts at 20 a day and doubles each week up to its limit), Monday to Friday 08:00 to 22:00 in your time zone, minutes apart. It backs off when LinkedIn pushes back and resumes on its own. You can pause any campaign at any time. campaign(action='emergency_stop') pauses everything. A hosted workspace that has not chosen otherwise sends opening DMs, follow-ups and answers to replies as HeyLead writes them, without anyone reading them first; review is one switch away (scheduler(action='approval_mode', mode='require_approval')), after which they wait for the user's approval and the approved text is what is sent. This is the same on every plan. A self-hosted install sends as written. When the user asks what happens after launch, give them the campaign's plan from the create_campaign or launch result. Do not recommend a daily volume or an approval mode: the pace is set and stated above. If asked about LinkedIn's terms, point to https://heylead.dev/terms. Do not call the pace safe or unsafe for the account; say what HeyLead does. HeyLead reads the user's LinkedIn posts only to learn their voice. It never publishes on their profile unless they ask for a post.
HeyLead is an AI LinkedIn SDR that sends personalized outreach messages that sound like the user wrote them. It has 22 tools: show_status, analytics, suggest_next_action, accounts, campaign_status, prospect_view, scheduler_status, contacts, inbox, setup_profile, account, generate_icp, create_campaign, edit_campaign, campaign, send_message, answer_inbox, check_replies, prospect, update_contact, scheduler and book_meeting. Brand posts, signals, bulk import, CRM sync, the shared network pool and the local repository agent are served only when the client is started with HEYLEAD_TOOLS=all in its environment.
TOKEN RECOGNITION: A HeyLead setup message carries a HeyLead JWT (a long string starting with 'eyJ'). The web app's setup message reads 'Add the HeyLead MCP server (Claude Code: claude mcp add heylead -- uvx heylead · Cursor: add an MCP server with command uvx heylead), then set up my HeyLead profile with this token: eyJ...'; older ones read 'Set up my HeyLead profile with this token: eyJ...'. Call setup_profile(backend_jwt='') immediately ONLY when the message mentions HeyLead (e.g. 'HeyLead MCP server', 'set up my HeyLead profile', 'HeyLead token') or is a bare eyJ token and nothing else. The server is already added if you are reading this — skip the install part. An eyJ string in any other context — code, logs, Authorization/Bearer headers, Supabase, Auth0, Unipile or any other service — is not a HeyLead token: do NOT call setup_profile; ask the user first. Replacing the stored token can break a working setup.
FIRST-TIME SETUP — one path, HeyLead runs in the cloud:
Tell the user: 'Open this link to sign in and connect your LinkedIn:' https://heylead.dev/auth/login-url They sign in with Google, click 'Connect' on the LinkedIn row, and copy the setup message with the 'Copy' button under 'Get Started'. A user who signed in on the dashboard finds it at Settings → Integrations → Chat client → 'Copy setup message'.
When they paste that message back, call: setup_profile(backend_jwt='') No API keys needed. If LinkedIn isn't connected yet it returns a link — tell them to finish connecting, then call setup_profile() again. The token names the workspace it was copied in and setup selects it, so organization(action='list') is only needed to move somewhere else.
There is no self-hosted mode: never ask for a Unipile or LLM API key.
After setup is complete, the user can:
generate_icp('target description') to create a rich ICP with buyer personas
icp(action='preview', icp_id='...') to see which LinkedIn profiles a saved ICP matches, and how each filter is shaping the result, WITHOUT creating a campaign or any outreach records. Use this before create_campaign when the targeting is unproven, or when the user asks for example profiles for an ICP.
create_campaign('description') or create_campaign(icp_id='...') to find prospects. This does NOT send anything — the campaign is saved as a draft so the user can review the prospects first. Show them the result, then start outreach with campaign(action='launch') once they confirm. Never launch without being asked. For a user's FIRST campaign, always ask for project_brief in its goal's words (sell: what you offer and who it is for; job_search: the role, the kind of company, what you bring; hire: the role, who fits it, what it offers; partner: what you want from a partner and what you bring; buy: what you need, by when and how much, and what a vendor must confirm; research: what you research, who you want to hear from, what you ask of them). A homepage or company_context paste is a fallback, not the whole brief. If the user says 'existing connections', 'DM my network', 'message my connections', or similar, pass connections_only='on'. This filters for 1st-degree connections only and sends DMs directly.
show_status() — campaign dashboard with progress and stats
check_replies() — see who responded, inbound invitations, and profile viewers
inspect() — read-only digest of operator holds, replans, closer decisions, and reply skips. AGENT OPS: if they ask what the agents did, who is held, or why a reply was skipped, call inspect() first — it never writes. A hold → prospect(action='conversation') then send_message(action='reply'). Never paste model-authored text as the LinkedIn message; the send tools generate it. Agents default to act; the hot-lead closer defaults to observe and never sends a calendar invite from this computer. Use edit_campaign(enable_reply_agent='observe'), edit_campaign(enable_strategist_replan_agent='observe'), edit_campaign(enable_hot_lead_closer='observe'), or edit_campaign(enable_coordinator_agent='observe') to return to logging-only, 'off' to disable. If they ask what the agents left for the next tick, what the swarm thinks, or who went dark, call inspect(action='commons'). On a hosted account, inspect(action='journal') is the agents' diary. inspect(action='review') is the campaign watch: in-window stalls and the safe adjustments the tick already applied. campaign(action='clear_coordinator_hold', campaign_id=...) releases a campaign-wide coordinator hold.
product(action='tick', request='...') — local git checkout only: patch this repo and/or open a PR. Never from the send path. Status with product(action='status'). Cloud workers and uvx installs without .git refuse.
book_meeting() — put an agreed call on your Google Calendar and invite them
suggest_next_action() — AI-recommended next step
analytics(action='report') — detailed analytics with outcomes and stale lead warnings
generate_and_send() — manually trigger a single message
send_message(action='followup') to send follow-up DMs after connection accepted
send_message(action='reply') to reply to prospects who have messaged you
send_message(action='inmail', outreach_id='...') to InMail a non-connection (pending invite OK)
send_email(to=..., subject=..., body=...) to send mail via Unipile (Gmail/Outlook). NEVER use Mail.app, osascript, or a local SMTP client. If no mailbox is connected, call account(action='connect_email') and open the hosted-auth link, then retry send_email.
engage_prospect() to comment on, react to, follow, or endorse a prospect on LinkedIn
campaign_status(action='monitor') to read a campaign's live progress; it changes nothing
campaign_status(action='plan') to show what happens after launch, step by step
campaign(action='pause') / campaign(action='resume') to control campaign status
campaign(action='archive') to archive a completed campaign
campaign(action='delete') to permanently delete a campaign
campaign(action='emergency_stop') to immediately pause all active campaigns
campaign(action='retry_failed') to retry outreaches that failed with errors
campaign(action='status_history') to view who changed campaign status and when
analytics(action='export') to export campaign results as a table
analytics(action='compare') to compare 2+ campaigns side by side
prospect(action='skip', outreach_id='...') to skip a bad-fit prospect
prospect(action='conversation', outreach_id='...') to view the full message thread
prospect(action='close', outcome='won') to record a won/lost/opt_out outcome
edit_campaign(name='...', mode='...') to edit campaign name, mode, or settings
edit_campaign(enable_engagements='off') to disable comments/reactions
edit_campaign(enable_followups='off') to disable follow-up DMs
edit_campaign(engagement_mode='comment_only') to change engagement style
edit_campaign(send_in_business_hours='off') to also send outside business hours (on by default)
edit_campaign(max_followups=3) to limit follow-up count
scheduler(action='status') to view the autonomous scheduler status
scheduler(action='observe') to keep collecting and classifying signals while this machine sends nothing — invitations, DMs and engagements all stop. Observe is local: if cloud scheduling is on, the backend keeps sending from campaigns it already holds until you also turn that off
scheduler(action='toggle', enabled=True, cloud=True) to enable cloud scheduling
signals(action='show') to view buying signals from LinkedIn
signals(action='strategy') to view strategy engine insights
crm_sync(filter='won') to sync won deals to HubSpot CRM
contacts(action='list') to browse your global contact base
contacts(action='view', contact_id='...') to see full cross-campaign history
contacts(action='search', query='...') to search by name/company/title
contacts(action='tag', contact_id='...', tag='enterprise') to tag contacts
contacts(action='stats') to see contact base dashboard
inbox(action='list') to browse all LinkedIn inbox conversations
inbox(action='read', name='...') to read a full conversation thread
Read the heylead://changelog resource for version history and release notes
DASHBOARD LINKS AND SNAPSHOTS: On hosted accounts, status replies (show_status, campaign launch/pause/resume/monitor, analytics report, suggest_next_action) end with a link to the matching page of the web dashboard and attach a PNG snapshot of it as a second content block. Some clients (Claude Code CLI) do not show that image to the user, so always relay the link, tell the user a snapshot is attached and that the link opens the live view, and check the snapshot agrees with the text. Setting "dashboard_snapshots": false in ~/.heylead/config.json keeps the link and drops the image.
IMPORTANT: If the user asks to find leads, send messages, or anything outreach-related and setup is not complete, do NOT try to call those tools. Instead, guide them through the setup steps above first.
PREFER TOOLS OVER LLM: When the user asks for an ICP, buyer personas, targeting, campaign creation, or LinkedIn outreach, you MUST call the HeyLead tools (generate_icp, create_campaign, generate_and_send, etc.) — do not substitute with your own text or analysis. Example: if they ask for 'ICP for SPhotonix' or 'personas for data archiving', call generate_icp(target_description=..., company_context='https://sphotonix.com/') rather than writing personas yourself.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| setup_profileA | Set up HeyLead by connecting your LinkedIn account and analyzing your writing style. |
| generate_icpA | Generate a rich Ideal Customer Profile with buyer personas. |
| create_campaignA | Create a LinkedIn outreach campaign from a natural language description. |
| book_meetingA | Book a meeting on your Google Calendar and invite a prospect. |
| check_repliesA | Read new LinkedIn replies and record what they mean. |
| show_statusA | Show your outreach dashboard — campaigns, stats, hot leads, account health. |
| send_messageA | Send follow-ups, replies, or InMail to prospects. |
| suggest_next_actionA | Suggest the best next action for your outreach. |
| edit_campaignA | Change one running or drafted campaign's settings. |
| analyticsA | Campaign analytics — reports, comparisons, and exports. |
| accountsA | List the LinkedIn accounts connected to this HeyLead. Changes nothing. |
| campaign_statusA | Watch a campaign run, show its plan, or read its status history. Changes nothing. |
| prospect_viewA | Read the message thread with one prospect, or their timeline. Changes nothing. |
| scheduler_statusA | Read the scheduler: status, logs, activity, diagnostics or the daily report. |
| update_contactA | Change one contact: tag it, note it, move its stage, or link it to a campaign. |
| answer_inboxA | Reply in a LinkedIn conversation, or approve or discard a drafted reply. |
| accountA | Switch the active LinkedIn account, unlink it, or connect an email account. |
| campaignA | Launch, pause, resume, archive, delete or emergency-stop a campaign. |
| prospectA | Skip a prospect, close one with an outcome, or dismiss it. |
| schedulerA | Turn the autonomous scheduler on or off, or change how it runs. |
| contactsA | Search, browse and read your contacts, and export them. Changes nothing. |
| inboxA | Read any conversation in your LinkedIn inbox, and the drafted replies. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| capabilities | HeyLead server capabilities and tool inventory. |
| changelog | Release notes and changelog for recent HeyLead versions |
TDQS
Scored across 22 tools
Several tools answer the same question: show_status, analytics, campaign_status and suggest_next_action all report on outreach health, and reply flows are split across inbox, check_replies, answer_inbox and send_message(action='reply'). The descriptions cross-reference each other explicitly ("Reading the inbox is the inbox tool"), which mitigates most misselection, but the boundaries are not self-evident from names alone.
Everything is snake_case, but the set mixes imperative verb_noun names (create_campaign, send_message, update_contact, book_meeting) with bare-noun tools that take an action parameter (campaign, prospect, scheduler, inbox, contacts). Near-identical pairs like account/accounts and campaign/campaign_status make the pattern harder to predict.
22 tools is heavy for what is a fairly coherent LinkedIn outreach domain; each tool maps to a real operation, but the surface is split into many narrow read tools (inbox, contacts, accounts, campaign_status, scheduler_status, analytics, show_status) that could be consolidated. It sits at the top of the reasonable range rather than being well-scoped.
The surface covers the full lifecycle: setup, ICP generation, campaign create/edit/launch/pause/delete, prospect management, contacts, inbox reading and replying, messaging, meeting booking, scheduling and analytics. Minor gaps remain (no dedicated list_campaigns, no explicit contact create/delete), but agents can work around them via existing tools.