# 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, 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 |
| **Analytics** | Funnel reports, conversion rates, stale lead detection, engagement ROI, experiment hypotheses |
| **Autonomous Scheduling** | 24/7 local or cloud scheduler — invitations, follow-ups, reply checks, engagements |

## Typical Workflow

```
1. setup_profile(backend_jwt="...")     → Connect LinkedIn account
2. generate_icp(target="CTOs fintech") → Create buyer personas
3. create_campaign(target="...", icp_id="...") → Find prospects, start outreach
4. toggle_scheduler(enabled=True)       → Autonomous: invitations → follow-ups → replies
5. check_replies() / show_status()      → Monitor pipeline
6. close_outreach(outcome="won")        → Track conversions
```

## Authentication

- Google OAuth → JWT token → pass to `setup_profile(backend_jwt="...")`
- No API keys needed — backend proxies LLM calls (Gemini 2.0 Flash)
- Optional: bring your own key (Gemini/Claude/OpenAI) via `setup_profile(llm_api_key="...")`

## All 31 Tools

### Setup & Accounts
| Tool | Description |
|------|-------------|
| `setup_profile` | Connect LinkedIn, analyze writing style, create voice signature. Required first step for SDR onboarding. |
| `list_linkedin_accounts` | List all connected LinkedIn accounts |
| `switch_account` | Show accounts and start switch flow |
| `switch_account_to` | Switch to a specific LinkedIn account by ID |
| `unlink_account` | Disconnect LinkedIn from HeyLead |

### ICP & Targeting
| Tool | Description |
|------|-------------|
| `generate_icp` | Create Ideal Customer Profiles with buyer personas, pain points, fears, barriers, and LinkedIn search parameters. Target audience segmentation and customer profiling. |

### Campaign Lifecycle
| Tool | Description |
|------|-------------|
| `create_campaign` | Create a LinkedIn outreach campaign. Supports lead generation, prospect discovery, SDR automation, cold outreach, and targeted B2B sales campaigns with AI-powered ICP-based targeting. |
| `edit_campaign` | Update campaign name, mode, booking link, offerings, case studies, or messaging preferences |
| `pause_campaign` | Pause an active campaign, stopping all outreach |
| `resume_campaign` | Resume a paused campaign |
| `archive_campaign` | Mark a campaign as completed |
| `delete_campaign` | Permanently delete a campaign and all its data |

### Outreach Execution
| Tool | Description |
|------|-------------|
| `generate_and_send` | Generate and send personalized LinkedIn invitation. Cold outreach, connection request, voice-matched personalized messaging. |
| `send_followup` | Send follow-up DM after connection accepted. Drip sequence, multi-touch nurture campaign. |
| `reply_to_prospect` | Auto-reply to prospect messages. Detects sentiment, advances positive leads toward meetings. |
| `engage_prospect` | Comment on or react to prospect's LinkedIn posts. Social selling warm-up and LinkedIn engagement. |

### Review & Approval
| Tool | Description |
|------|-------------|
| `approve_outreach` | Approve, reject, edit, or skip a copilot-generated message |
| `suggest_next_action` | AI recommends the best next action, prioritized by impact |
| `show_conversation` | View the full DM thread and engagement history with a prospect |
| `skip_prospect` | Remove a bad-fit prospect from the outreach queue |

### Analytics & Reporting
| Tool | Description |
|------|-------------|
| `show_status` | Dashboard — campaigns, stats, hot leads, account health |
| `check_replies` | Check for new LinkedIn replies, classify sentiment, surface hot leads. Inbox monitoring, lead responses, conversation tracking. |
| `campaign_report` | Detailed analytics — funnel, outcomes, stale leads, engagement ROI |
| `export_campaign` | Export campaign results as a formatted table |
| `compare_campaigns` | Side-by-side comparison of 2+ campaigns with winner highlights |
| `close_outreach` | Record outcome — won, lost, or opted out — with conversion analytics |
| `experiment_loop` | Analyze performance and generate experiment hypotheses |

### Automation
| Tool | Description |
|------|-------------|
| `toggle_scheduler` | Enable/disable autonomous scheduler (local or cloud 24/7) |
| `scheduler_status` | View scheduler state, pending jobs, recent activity |
| `emergency_stop` | Immediately pause ALL active campaigns — kill switch |
| `retry_failed` | Retry outreaches that failed with errors |

## Installation

**Cursor:** [One-click install](cursor://anysphere.cursor-deeplink/mcp/install?name=heylead&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJoZXlsZWFkIl19)

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

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

**Manual (any MCP client):**
```json
{
  "heylead": {
    "command": "uvx",
    "args": ["heylead"]
  }
}
```

## Transport

- **stdio** (default) — for local MCP clients (Cursor, Claude Code, etc.)
- **streamable-http** — coming soon for remote/cloud agents
