# RocketSDR MCP — LLM Quick Reference

This file is a concise, machine‑readable guide for LLMs/agents integrating with RocketSDR MCP.
It includes critical nuance: strict targeting resolution, max leads limits, and common pitfalls.

Base URL:
https://api.rocketsdr.ai/api/mcp

Auth:
Preferred for remote connectors: Authorization: Bearer YOUR_ACCESS_TOKEN
Compatibility for scripts / legacy clients: X-API-Key: YOUR_API_KEY
Behavior: either auth mode maps to a single RocketSDR account; all actions happen in that account context.
Claude / ChatGPT connector fields:
- Server URL: https://api.rocketsdr.ai/api/mcp
- OAuth Client ID: rocketsdr
- OAuth Client Secret: leave blank

JSON-RPC envelope:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": {}
  }
}

Handshake (optional but recommended for MCP-native clients):
1) POST initialize
2) POST initialized (notification)
Then call tools/list and tools/call.

If you include the MCP-Protocol-Version header, use:
MCP-Protocol-Version: 2025-06-18

Streamable HTTP (optional):
- If Accept: text/event-stream is sent, responses are returned as SSE events.
- GET /api/mcp with Accept: text/event-stream opens a keep-alive SSE stream (no server messages yet).
- If initialize returns Mcp-Session-Id, include it on subsequent requests (optional).

Recommended agent workflow:
1) list_products + list_personas (ensure IDs exist)
2) list_senders (collect email account IDs and/or LinkedIn usernames)
3) search_targeting for ambiguous inputs (title/location/industry/function/seniority)
4) preview_leads and iterate until audience size looks reasonable
5) preview_email (optional) — pass a sample lead from step 4 to show what the first email will look like
6) create_campaign (or create_campaign_draft then finalize_campaign_draft)

Targeting discovery:
tool: search_targeting
args: { query, type }
type ∈ { location, title, industry, function, seniority }
note: use discovery before preview/create to avoid resolution failures

Rate limits (per account, per day):
- preview_leads: 20
- create_campaign / finalize_campaign_draft: 10

Supported seniority values (recommended labels):
- Owner / Partner
- CXO
- Vice President
- Director
- Experienced Manager
- Entry Level Manager
- Strategic
- Senior
- Entry Level
- In Training

Supported function values (recommended labels):
- Accounting
- Administrative
- Arts and Design
- Business Development
- Community and Social Services
- Consulting
- Education
- Engineering
- Entrepreneurship
- Finance
- Healthcare Services
- Human Resources
- Information Technology
- Legal
- Marketing
- Media and Communication
- Military and Protective Services
- Operations
- Product Management
- Program and Project Management
- Purchasing
- Quality Assurance
- Real Estate
- Research
- Sales
- Customer Success and Support

Resolution rules (strict):
- Resolvable fields: locations, job_titles, industries, functions, seniority
- If ANY resolvable input cannot be mapped to a supported value, the request fails
- Non-resolvable passthrough fields: companies, keywords, company_size_min/max, qualifiers

Over-filtering pitfall:
- Avoid specifying job_titles AND functions AND seniority unless you truly want a narrow audience.
- Common pattern: locations + job_titles (+ company_size) OR locations + functions + seniority (+ company_size).

Preview leads:
tool: preview_leads
args (optional): locations, job_titles, functions, seniority, industries, companies, keywords, company_size_min, company_size_max, qualifiers
returns: estimated total + sample leads
max leads per campaign: 2500
tip: avoid over‑filtering; job_titles alone often sufficient, or function+seniority without job_titles

Preview email:
tool: preview_email
required: product_id, persona_id
optional: sample_lead (required: name, title, company — optional: email, linkedin_url, notes), step (default 1), instructions, outreach (language, framework), signature
returns: subject + generated HTML email body
tip: pass a lead from preview_leads as sample_lead for a realistic preview

Campaign creation (final):
tool: create_campaign
required: name, product_id, persona_id
optional: targeting fields, sender_ids, sender_emails, sender_usernames, sender_signatures, workflow, settings, outreach, max_leads, autopilot, ab_test, initial_offset
defaults: max_leads=200, workflow=4 emails (0,3,4,5), framework=classic
strict targeting resolution for resolvable fields
notes:
- if any resolvable targeting field fails resolution, the request fails (no partial creation)
- max_leads must be 1..2500

CSV campaign creation:
- set type=csv
- option A (inline): pass csv_content as raw CSV text (header + data rows)
- optional csv_filename (default: campaign.csv)
- option B (stateless pre-upload): call get_csv_upload_url, upload CSV via multipart POST (uploadUrl + formFields), then pass gcsUrl as csv_url
- for create_campaign with type=csv, provide either csv_content or csv_url
- CSV parser expects required columns:
  - contact name (aliases accepted: name, full name, contact, fullname, person, lead name, lead)
  - company (aliases accepted: company name, organization, org, firm, employer, business)
- optional columns include: email, title/job title, linkedin/linkedin url, location, notes/csv notes

CSV pre-upload tool:
tool: get_csv_upload_url
args (optional): filename
returns: uploadUrl, uploadMethod=POST, formFields, gcsUrl (use as csv_url), maxSizeBytes=2097152
enforcement: filename sanitized to .csv, upload hard-limited to 2 MB

CSV one-shot example:
tool: create_campaign
args:
{
  "name": "CSV Outreach Batch 1",
  "type": "csv",
  "product_id": 12,
  "persona_id": 7,
  "csv_content": "contact name,email,company,title,notes\nAda Lovelace,ada@example.com,Analytical Engine,Founder,Asked for a technical walkthrough\nGrace Hopper,grace@example.com,Compilers Inc,VP Engineering,Interested in migration timeline"
}

CSV pre-upload example:
1) get_csv_upload_url
{
  "filename": "batch-1.csv"
}
2) POST csv bytes to uploadUrl from step 1 using returned formFields (multipart form upload)
3) create_campaign
{
  "name": "CSV Outreach Batch 1",
  "type": "csv",
  "product_id": 12,
  "persona_id": 7,
  "csv_url": "https://storage.googleapis.com/BUCKET/campaigns/ACCOUNT_ID/UUID-batch-1.csv"
}

Workflow:
- If workflow not provided, default is 4 email steps.
- To control campaign messaging, tone, event references, CTAs, and copy guidance, set `workflow[].emailConfig.content` with `mode=instruction`.
- Use `outreach.researchScript` only for research guidance, such as what company or person signals to look for before writing.
- Do not put campaign copy instructions in `outreach.researchScript`; those belong in step-level workflow instructions.

Signature modes (mutually exclusive):
- Campaign-level: set outreach.signature with structured fields: fullName, title, organization, website
- Per-sender: pass sender_signatures (object keyed by sender ID or email → signature string); automatically enables useCustomSignatures
  - E.g. sender_signatures: {"sender-uuid": "Best,\nJohn Smith\nCEO, Acme"}
  - All resolved senders must have a signature entry; partial config is rejected with an error listing missing senders
- preview_email accepts a top-level signature arg (supports fullName/title/organization/website and rawSignature for ad-hoc previews)

Senders:
- sender_ids: email account IDs (from list_senders → Email Accounts)
- sender_emails: resolves to email account OR LinkedIn sender by email
- sender_usernames: resolves to LinkedIn sender (login email)
- empty senders are allowed, but campaign may not send until senders are configured.

Draft flow:
tool: create_campaign_draft (partial data allowed)
tool: finalize_campaign_draft (required: campaign_id, name, product_id, persona_id)

Draft strategy:
- Use drafts when you want to persist a partially configured campaign and finalize later.
- Finalization performs full validation and enqueues preprocessing.

CSV draft/finalize:
- create_campaign_draft accepts type=csv and optional csv_content/csv_filename/csv_url
- finalize_campaign_draft also accepts optional csv_content/csv_filename/csv_url
- if CSV was uploaded in draft, finalize can run without re-sending CSV

CSV draft example:
1) create_campaign_draft
{
  "name": "CSV Draft Campaign",
  "type": "csv",
  "csv_filename": "draft-leads.csv",
  "csv_content": "contact name,email,company,title,notes\nLinus Torvalds,linus@example.com,Kernel Org,Maintainer,Prefers concise technical outreach"
}

2) finalize_campaign_draft
{
  "campaign_id": "DRAFT_ID",
  "name": "CSV Draft Campaign",
  "type": "csv",
  "product_id": 12,
  "persona_id": 7
}

Assets:
list_products, create_product
list_personas, create_persona

ID types:
- product_id: integer
- persona_id: integer
- email sender IDs used in campaigns: email account UUID string
- LinkedIn sender IDs: UUID string

Senders:
list_senders → email account IDs + LinkedIn usernames
sender_ids = email account IDs
sender_emails resolves to email or LinkedIn
sender_usernames = LinkedIn login emails

A/B testing:
- create_campaign/create_campaign_draft/finalize_campaign_draft support `ab_test`
- shape:
  - enabled: boolean
  - split: [A_percent, B_percent] (e.g., [50,50])
  - winner_metric: one of responseRate, positiveResponseRate, meetingRate, openRate, clickRate
  - variant_b: optional overrides for persona_id, outreach, workflow
- optional `initial_offset` helps create non-overlapping cohorts across campaigns using same ICP.
- use `get_campaign_ab_metrics` with `campaign_id` to inspect variant-level results.

Analytics:
list_campaigns → summary metrics + rates
get_campaign → config + detailed metrics
get_campaign_ab_metrics → variant-level A/B metrics for a campaign

Analytics notes:
- list_campaigns returns per-campaign metrics like sent/opened/clicked/responses/meetings and derived rates.
- Use get_campaign for detailed config and metrics for a single campaign.

Campaign management:
- update_campaign_status
  - required: campaign_id, status
  - status ∈ {active, paused, completed}
  - use to pause underperforming campaigns or resume paused campaigns
- extend_campaign
  - required: campaign_id
  - optional: additional_leads (default 100, max 500 per call)
  - use to scale campaigns that are already working instead of creating a duplicate campaign
- get_campaign_leads
  - required: campaign_id
  - optional: status, sentiment, limit, page
  - use for lead-level inspection when deciding whether to scale, pause, or complete a campaign

Limits:
max_leads must be 1..2500 (default 200)