# Using Saava from an AI assistant

These instructions live at https://docs.saava.io (plain text: https://docs.saava.io/mcp.md). Saava finds people showing buying signals, scores them against the user's targeting, and reaches them on LinkedIn and email. An assistant connected through MCP Connect can do almost everything the app does, from the chat: read leads and replies, build lists, watch for signals, write each person's messages, and reply.

## Connect

The connector URL is `https://www.saava.io/api/mcp`. Add it as a custom connector (remote MCP server) in the assistant; the user signs in to Saava and approves one workspace. The connection sees only that workspace, and the user can remove it at any time from Integrations, MCP Connect, which stops access immediately.

- **Claude**: Settings, Connectors, Add custom connector, paste the URL. Needs a paid Claude plan.
- **ChatGPT**: Settings, Connectors (developer mode), add a custom connector with the URL.
- **Codex and Cursor**: add a remote MCP server with the URL in the MCP settings.

## Rules for the assistant

- **Ask before anything reaches a real person.** Queuing messages, approving drafts, adding a lead to a campaign and sending a reply all go out under the user's name. Show the user the exact text or the people, and wait for a clear yes.
- **Check the account first.** `get_account_status` says the plan, the credits left and whether sending is paused. A trial is free to use; a paid plan spends credits.
- **Targeting and the business profile are the user's.** Suggest changes; change them only when the user asks.
- **Write from the person, not a template.** Use what `get_lead` returns about someone (their role, company, and what they posted or did) and keep messages short.

## Common workflows

### See what is happening

`get_account_status` for the plan and credits, `list_campaigns` and `get_campaign_performance` for results, and `list_inbox` then `get_conversation` for replies.

### Find and organise leads

`list_leads` with filters (fit, stage, source, date), `get_lead` for one person, `create_lead_list` and `add_leads_to_list` to group them, and `update_lead` to record a stage or an outcome.

### Write each person's messages yourself

Saava can send messages the assistant writes, one per lead, instead of a shared template. No add-on is needed: queuing them costs 0.5 credits per message (free on a trial).

1. `list_campaigns` and pick a campaign whose `messages_written_by` is `your_ai` or `saava_ai`. A campaign that sends one template to everyone can't carry per-lead text. If there is none, create one with `create_campaign`: confirm its name, the LinkedIn accounts it sends from (`list_linkedin_senders`) and its steps with the user. It starts empty, so creating it sends nothing.
2. `get_campaign_message_shape` for that campaign: whether it sends a connection note, how many follow-ups, and the limits for each.
3. Write one message set per lead from their own details, show them to the user, then `queue_custom_messages` (up to 50 leads per call).
4. The messages wait in AI Messages for the user's approval, or send straight away if the campaign approves automatically. `list_message_drafts`, `approve_message_drafts` and `dismiss_message_drafts` work that queue from the chat.

### Rename a campaign or change its wording

`rename_campaign` changes only the name. To change what a campaign says, `get_campaign_messages` shows each step's words and wait, and `update_campaign_messages` changes just the steps you pass. It works on a live campaign: the campaign keeps its id, its people and its stats, and new sends use the new text. Show the user the exact new wording and wait for a clear yes before calling it. Adding, removing or turning off a step is done in the app.

### Control how AI messages are written and sent

`get_campaign_settings` shows whether a campaign's messages wait for approval, its guidance to the writer, its maximum note and follow-up lengths, and which business-profile fields the writer reads. `update_campaign_settings` changes them: `auto_approve: false` makes every new message wait for approval, `guidance` sets the campaign's notes to the writer, and `max_note_chars` / `max_followup_chars` set shorter limits (a message over its limit loses whole sentences, never half of one). Turning auto-approve on needs the user's explicit OK and `confirm_auto_send: true`.

`export_message_history` returns every message written for a campaign with ids, timestamps, status, any review hold and what it was written from, a page at a time. `stop_lead_outreach` stops all remaining automated messages to one person, including follow-ups already scheduled, without deleting anything; confirm with the user first.

### Watch for buying signals

`create_intent_monitor` from a plain-English description of what to watch for (for example: companies hiring their first SDR), `list_intent_monitors` to see them, and `list_sources` or `add_sources` for the LinkedIn profiles whose audience Saava follows.

### Reply to people

`list_inbox`, then `get_conversation`, then draft a reply, show it to the user, and `send_linkedin_reply` once they approve.

### Keep the pitch current

`get_business_profile` and `update_business_profile` hold what the user sells, to whom, and the proof. Every message Saava writes is built from it, so keep it accurate. `get_targeting` shows who they sell to.

## Tool reference

Every tool the connector offers, as the assistant sees it.

### Leads, lists, campaigns and inbox

- `get_account_status`: Snapshot of this Saava workspace: plan, billing state, credits, connected channels (LinkedIn outreach / email), and totals for leads, lead lists and campaigns. Call this first to orient.
- `list_leads`: Search and filter this workspace's leads. Returns compact rows sorted by newest or by ICP match. Statuses: active, snoozed, bad_fit, client. Outcomes: qualified, booked, won, not_a_fit.
- `get_lead`: Full detail for one lead by id: contact info, ICP score and reasoning, engagement, outreach status and which campaign it went to.
- `update_lead`: Update one lead: set status (active/snoozed/bad_fit/client), set outcome (qualified/booked/won/not_a_fit), or mark good_fit / bad_fit (mutually exclusive; marking one clears the other). Provide only the fields to change.
- `list_lead_lists`: All lead lists in this workspace with member counts and type.
- `create_lead_list`: Create a new lead list. Returns the new list's id. `type` is optional and defaults to 'standard' — the kind you want for a list you fill yourself.
- `add_leads_to_list`: Add up to 200 leads (by id) to a lead list. Already-present leads are skipped.
- `remove_leads_from_list`: Remove leads (by id) from a lead list. The leads themselves are kept.
- `list_campaigns`: All outreach campaigns in this workspace (LinkedIn via the connected sender network, plus email campaigns if connected), with status and launch state.
- `get_campaign_performance`: Outreach funnel for a time window: per-campaign and per-sender invites sent, accepted, and replies. Defaults to the last 30 days.
- `pause_campaign`: Pause a LinkedIn campaign. Sticks until resumed: Saava also stops feeding it leads.
- `resume_campaign`: Resume a paused LinkedIn campaign so sending and lead routing restart.
- `push_lead_to_campaign`: Add one lead to a LinkedIn campaign so outreach actually goes to them. The lead needs a LinkedIn URL. This queues a REAL message sequence to a REAL person — confirm with the user before calling.
- `list_inbox`: Recent LinkedIn outreach conversations: who they're with, the last message, and unread state. Use unread_only to fetch just threads awaiting a reply.
- `get_conversation`: Full message history of one LinkedIn conversation by conversation_id.
- `send_linkedin_reply`: Send a reply into an existing LinkedIn conversation, as the user. This DELIVERS A REAL MESSAGE immediately — always show the user the exact text and get their go-ahead first.
- `get_business_profile`: The workspace's business profile (what they sell, to whom, proof points) — the grounding every AI-written message uses.
- `update_business_profile`: Update fields of the business profile. Only the fields provided are changed; everything else is kept. This grounds all AI-written outreach, so keep it factual.
- `get_targeting`: The workspace's saved targeting (ICP): titles, industries, locations, seniority, company sizes, and the free-text description. Targeting edits happen on Saava's Targeting page — this is read-only.
- `get_plans`: What each Saava plan costs and includes, and what the current plan allows. Call this before suggesting an upgrade — upgrade_plan requires the price from here.
- `upgrade_plan`: Move this workspace UP to a higher plan and charge the card on file for the prorated difference immediately. Confirm the price with the customer first: this spends their money. `confirm_monthly_usd` must match the plan's monthly price from get_plans. Downgrades and cancellations are not available here — those are done in Saava.
- `rename_campaign`: Rename a LinkedIn campaign. Only the name changes: the campaign, its id, its people and its stats stay as they are. Names are up to 120 characters.
- `get_campaign_messages`: The words a LinkedIn campaign sends, step by step: the connection note, each follow-up with its wait (days after the step before) and whether it's on, and the InMail if it has one. Read this before update_campaign_messages; steps are numbered from 1.
- `update_campaign_messages`: Change the words or waits of a LinkedIn campaign, including a live one: it keeps its id, its people and its stats, and carries on sending with the new text (it pauses for a moment while the change is made, then resumes). Pass only what changes: the connection note, and/or follow-up steps by number (get_campaign_messages) with a new message and/or delay_days, and/or the InMail subject and message. Adding, removing or turning off a step is done in the app. These are real messages to real people under the user's name: show the user the exact new text and get explicit confirmation before calling.
- `get_campaign_settings`: How Saava writes and sends for one AI-messages LinkedIn campaign: whether messages send without review (auto_approve), the campaign's guidance to the writer, the maximum note and follow-up lengths, the allowed ranges, and which business-profile fields the writer reads.
- `update_campaign_settings`: Change how Saava writes and sends for one AI-messages LinkedIn campaign. Only what you pass changes. auto_approve false makes every new message wait in the AI Messages queue for approval. auto_approve true sends future messages without review: it needs confirm_auto_send true and the user's explicit OK, and it does not release messages already waiting. guidance: the campaign's notes to the writer, up to 400 characters ("" clears it). max_note_chars (100-270) and max_followup_chars (150-500) cap new messages; a message over its cap is shortened by whole sentences, never cut mid-sentence. Voice is set in the business profile with update_business_profile.
- `export_message_history`: The full record of messages for audit, newest first, with ids and timestamps: per lead, the connection note, each follow-up and the InMail as written, the status (draft, approved, sent = handed to LinkedIn sending, dismissed, failed), created/approved/sent times, whether it was held for review and why, and what it was written from (how they engaged, the post's URL and author, whether the post is theirs, the role and company used). Follow-ups after the first are sent by LinkedIn's sequence on their waits once the person accepts; replies and delivered messages are in get_conversation. Page with `before` (the next_before value).
- `stop_lead_outreach`: Stop every remaining automated message to one person in one LinkedIn campaign, including follow-ups LinkedIn's sequence would send on its own, and dismiss any unsent messages for them. Nothing is deleted: the conversation and the message history stay, and the user can still message them by hand. Use it for anyone who shouldn't hear from the campaign again. It can't be undone from here, so confirm with the user first.

### Messages

- `get_campaign_message_shape`: What one message for a campaign must contain before you write it: whether it sends a connection note, how many follow-ups (in order), whether it sends an InMail to open profiles, the character limits, and the personalisation tokens allowed. Call this before queue_custom_messages.
- `queue_custom_messages`: Queue messages YOU wrote, one per lead, for a per-lead campaign (messages_written_by your_ai or saava_ai; up to 50 leads per call). Each lead's text must match the campaign's shape from get_campaign_message_shape. Costs 0.5 credits per message queued (free on a trial). Messages land in the AI Messages review queue — or send straight away if the campaign auto-approves. These are real messages to real people under the user's name: show the user the exact text and get explicit confirmation before calling. A lead that already has a sent or approved draft in this campaign is skipped; an unsent draft is replaced at no charge.
- `list_message_drafts`: Messages waiting in the AI Messages queue (or recently sent/failed): who they're for, the text, the status, and who wrote them. Filter by campaign and status.
- `approve_message_drafts`: Approve queued messages so they send: either specific draft ids, or everything waiting in one campaign. Sending happens in the background, one lead at a time. This sends real messages to real people — confirm with the user first. Drafts flagged sensitive_context are skipped unless include_sensitive is true.
- `dismiss_message_drafts`: Dismiss queued messages so they never send. The lead stays in the workspace; only the pending message is withdrawn.

### Setup

- `list_linkedin_senders`: The LinkedIn accounts this workspace sends from, with their ids. Use an id in create_campaign's sender_ids.
- `create_campaign`: Create a LinkedIn campaign whose messages YOU write, one set per lead (messages_written_by: your_ai). No add-on is needed; each message costs the same as queue_custom_messages when you queue it (free on a trial). The campaign starts with nobody in it: people join only when you queue their messages with queue_custom_messages, so creating it sends nothing. Confirm the name, the sending accounts and the steps with the user first. Steps: an optional connection note, then up to 4 follow-up messages, each sent a number of days after the one before.
- `list_campaign_lists`: Which lead lists feed a campaign (a campaign sends to the people in its attached lists, continuously). Shows attached and previously-detached lists with sync counts.
- `attach_lists_to_campaign`: Plug lead lists into a LinkedIn campaign so it keeps sending to everyone in them, now and as the lists grow. Leads start going out within minutes, subject to the campaign's fit floor and daily limits. This causes real outreach — confirm with the user first.
- `detach_list_from_campaign`: Stop a lead list feeding a campaign. Only FUTURE sends stop — people already in the sequence keep receiving it. Re-attaching later resumes where it left off.
- `list_sources`: The LinkedIn profiles and company pages this workspace watches. Everyone who likes or comments on their posts is pulled in as a lead and scored against the targeting.
- `add_sources`: Watch LinkedIn profiles or company pages (up to 20 URLs per call). Their engagers start arriving as leads within minutes. Counts against the plan's source limit; re-adding one already watched just refreshes it.
- `list_intent_monitors`: The intent monitors in this workspace — each watches LinkedIn posts for a buying signal described in plain English and turns matching posters into leads.
- `create_intent_monitor`: Create an intent monitor from a plain-English description of the buying signal to watch for (e.g. "companies hiring their first SDR"). Saava turns it into search keywords and starts scanning right away. Optionally send its leads to an existing lead list. Counts against the plan's monitor limit.