# HeyLead — Agent Integration Guide

## What HeyLead Does

HeyLead is an autonomous LinkedIn SDR (Sales Development Representative) that runs entirely via MCP tools. It finds prospects, sends personalized outreach, follows up, tracks replies, and closes deals — all through natural language commands.

**Use cases:** LinkedIn lead generation, cold outreach automation, B2B prospecting, SDR automation, campaign management, ICP (Ideal Customer Profile) generation, multi-touch drip sequences, engagement warm-ups, and outreach analytics.

## Capabilities

| Category | What it does |
|----------|-------------|
| **ICP Generation** | RAG-powered buyer personas with pain points, fears, barriers, and LinkedIn search parameters |
| **Campaign Management** | Create, launch, pause, resume, archive, delete, and compare outreach campaigns |
| **Outreach Automation** | Personalized connection invitations, follow-up DMs, engagement warm-ups (comments, likes) |
| **Reply Handling** | Sentiment classification (positive/negative/question/neutral), auto-responses, meeting scheduling |
| **Intent Signals** | Company news, page engagement, website visitors, profile viewers — compounded into outreach angles |
| **Analytics** | Funnel reports, conversion rates, stale lead detection, engagement ROI |
| **Autonomous Scheduling** | 24/7 local + cloud scheduler. Launching a campaign commissions the cloud, so outreach continues with the laptop closed; the local scheduler then stands down for everything the backend sends (invitations, follow-ups, DMs, engagements, follows, endorsements, email fallbacks, campaign top-ups, brand posts) and keeps signals, replies, InMails and strategy |

## Typical Workflow

```
1. setup_profile(backend_jwt="...")             → Connect LinkedIn account
2. generate_icp(target_description="CTOs fintech") → Create buyer personas
3. create_campaign(target_description="...", icp_id="...") → Find prospects (saved as a draft)
4. campaign(action="launch", campaign_id="...") → Start outreach — nothing sends before this
                                                   (hosted accounts: also starts 24/7 cloud sending)
5. scheduler(action="toggle", enabled=True)     → Autonomous: invitations → follow-ups → replies
6. check_replies() / show_status()              → Monitor pipeline
7. prospect(action="close", outcome="won")      → Track conversions
```

## Authentication

- **Hosted (easiest):** the user signs in at <https://heylead.dev/auth/login-url>, connects LinkedIn, and pastes the resulting token message into chat → pass it to `setup_profile(backend_jwt="...")`. LinkedIn access and AI calls are handled by the HeyLead backend.
- **Self-hosted:** a Unipile account (LinkedIn access) plus the user's own LLM key in `~/.heylead/config.json`; run `setup_profile()` with no token.
- Optional: bring your own key (Gemini/Claude/OpenAI) via `setup_profile(llm_api_key="...")`.

## All 30 Tools

### Setup & Account
| Tool | Description |
|------|-------------|
| `setup_profile` | Connect LinkedIn, analyze writing style, create voice signature. Required first step. |
| `account` | Manage LinkedIn accounts — list, switch, or disconnect |

### ICP & Targeting
| Tool | Description |
|------|-------------|
| `generate_icp` | Create Ideal Customer Profiles with buyer personas, pain points, fears, barriers, and LinkedIn search parameters |
| `icp` | Preview which LinkedIn profiles a saved ICP matches, and how each filter shapes the result, without creating a campaign or any outreach records |

### Campaign Lifecycle
| Tool | Description |
|------|-------------|
| `create_campaign` | Create an outreach campaign (as a draft) from a natural language description, with ICP-based targeting |
| `campaign` | Campaign lifecycle — launch, pause, resume, archive, delete, emergency stop, retry failed |
| `edit_campaign` | Update campaign name, mode, booking link, offerings, case studies, or messaging preferences |
| `import_prospects` | Import prospects from CSV data into a campaign |

### Outreach Execution
| Tool | Description |
|------|-------------|
| `generate_and_send` | Generate and send a personalized LinkedIn message — cold outreach, connection requests, voice-matched messaging |
| `send_message` | Send follow-ups, replies, or voice memos to prospects — drip sequences, multi-touch nurture |
| `engage_prospect` | Comment on, react to, follow, or endorse a prospect — social-selling warm-up |
| `inbox` | Browse and read LinkedIn inbox messages directly |
| `backfill_inbox` | Process unreplied inbox messages through the inbound qualification pipeline |
| `create_post` | Generate and publish a voice-matched post to LinkedIn, X/Twitter, or both |

### Prospects & Contacts
| Tool | Description |
|------|-------------|
| `prospect` | Manage prospects — skip, close with outcome (won/lost/opted out), view conversation or timeline |
| `contacts` | Search, browse, and manage the global contact base; direct LinkedIn people lookup |
| `partner` | Track follow-ups with business partners, vendors, and investors |
| `crm_sync` | Sync campaign contacts and deals to HubSpot CRM |

### Insights & Analytics
| Tool | Description |
|------|-------------|
| `show_status` | Dashboard — campaigns, stats, hot leads, account health |
| `check_replies` | Check for new replies, classify sentiment, surface hot leads |
| `analytics` | Campaign analytics — reports, comparisons, and exports |
| `suggest_next_action` | Recommend the best next action, prioritized by impact |
| `signals` | View and analyze buying signals — news, company engagement, website visitors, profile viewers |
| `manage_watchlist` | Add, remove, and list signal keyword watchlists |
| `network` | Network intelligence — leverage all connected accounts as a distributed pool |

### Brand & Profile
| Tool | Description |
|------|-------------|
| `brand_strategy` | Analyze and improve the user's LinkedIn personal brand to drive inbound leads |
| `profile` | View and restore LinkedIn profile change history |

### Automation
| Tool | Description |
|------|-------------|
| `scheduler` | Autonomous scheduler — status, toggle on/off, always-on mode (local or cloud 24/7) |

## Installation

**Claude Code:**
```bash
claude mcp add heylead -- uvx heylead
```

**Cursor:** Settings → MCP → Add new MCP server → Name: `heylead`, Command: `uvx heylead`

**OpenClaw** (`openclaw.json`):
```json
{
  "mcp": {
    "servers": [
      {
        "name": "heylead",
        "command": "uvx",
        "args": ["heylead"]
      }
    ]
  }
}
```

**Any MCP client:**
```json
{
  "heylead": {
    "command": "uvx",
    "args": ["heylead"]
  }
}
```

## Transport

- **stdio** — `uvx heylead`; update with `uvx --refresh heylead`
- **streamable-http** — `heylead --transport streamable-http` for self-hosted HTTP serving
