ScaliQScaliQ API
API key
On this page

One-prompt campaign setup (for AI agents)

Audience: Claude, Cursor, Codex, ChatGPT, and other MCP clients that should set up a first ScaliQ outreach campaign from a single user prompt.

Public URL: https://docs.scaliq.ai/agent-setup

User prompt example:
“Fetch https://docs.scaliq.ai/agent-setup and start my first campaign.”

Follow this runbook in order. Do not skip the LinkedIn gate. Do not invent LinkedIn account ids. Confirm with the user before start_campaign.

0. Connect the MCP client (once per workspace)

ClientHow to connect
Claude.ai / Claude Desktop / Claude CodeAdd MCP URL https://mcp.scaliq.ai → Connect → Sign in with ScaliQ → review Allow access? (client name + redirect host) → Allow. Prefer Sign in; do not put an API key in Claude Advanced OAuth fields.
ChatGPTSame OAuth path as Claude: MCP URL → Connect → Sign in → Allow.
CodexSame OAuth Sign-in flow when the client supports MCP OAuth; otherwise use a Cursor-style API key (below).
CursorCreate a separate API key on API & MCP (any name other than MCP OAuth). Paste it in mcp.json as headers.X-API-Key. Never use the OAuth-minted MCP OAuth key in Cursor — reconnecting Claude rotates it.

Paid workspace required. Free/trial cannot mint API access.

Details: Connect Claude, MCP.

1. Read workspace readiness (do not guess)

Call, in any order:

  1. get_setup_status (GET /setup) — get-setup
  2. list_accounts (if you need account ids / today’s caps)
  3. get_credits (optional if get_setup_status.credits is enough)

Use get_setup_status so you know account counts, template count, campaign counts by status, and credits (including Lookalike) without inventing state.

2. LinkedIn gate — STOP if empty

If accounts.hasConnectedAccount is false (or list_accounts returns no connected accounts):

  1. Call create_linkedin_connect_link (POST /accounts/connect-link) — post-account-connect-link.
  2. Give the user the connectUrl and ask them to open it and finish LinkedIn sign-in in the browser. You cannot complete LinkedIn login yourself.
  3. Stop creating templates/campaigns until they confirm (or until you re-poll and see a connected account).
  4. Re-run get_setup_status / list_accounts. Seat/plan limits return 409 conflict — explain the message and stop.

Never invent, fake, or “simulate” a LinkedIn connect.

3. Ask the user (before creating anything)

Collect (or confirm) at least:

TopicWhy
ICPWho to search for (titles, industries, seniority)
Pitch / offeryourPitch on the agent (required)
GeographyCountries / regions for LinkedIn search
Timezone + weekdays + hoursComplete sendWhen (required). days must be lowercase full names: monday…sunday (not Mon / Mon-Fri)
LinkedIn accountId(s)From list_accounts — which sender(s) to use
Daily invite / message capsOptional; default is fine, or update_account_limits (0–30)

Do not invent account ids. Copy them from list_accounts.

4. Build the first campaign (tool order)

Run these tools in this order (pause if any step fails):

  1. create_template — manual agent with name, prompt, non-empty yourPitch, complete sendWhen, and ≥1 connected + active selectedAccounts (ids from list_accounts). If you get 403 account_disconnected, re-list accounts and fix the ids (or reconnect — see lifecycle below).
  2. create_manual_campaign — empty campaign (name only).
  3. assign_template — assign the new template to the campaign.
  4. search_linkedin — one page at a time via a connected account; respect rate limits; do not burst.
  5. add_leads_batch — add chosen profile URLs (1 credit per create).
  6. preview_lead — dry-run static invite note / first message on at least one lead.
  7. Confirm with the user — show preview + campaign summary; ask explicitly whether to start.
  8. start_campaign — only after explicit confirmation.

Optional: update_account_limits before start if they asked for specific daily caps.

5. Finish

After a successful start:

  1. Give the dashboard campaign URL:
    https://app.scaliq.ai/campaigns/{campaignId}/leads
  2. Remind them outreach follows the agent’s send window and daily caps.
  3. Offer pause / insights later (pause_campaign, get_insights_overview, get_recent_activity).

Account lifecycle (after setup)

NeedTools
Session broken but still “connected”Confirm → disconnect_linkedin_for_reconnect (may pause campaigns) → create_linkedin_reconnect_link → user opens URL → poll list_accounts
Already disconnected / failedcreate_linkedin_reconnect_link → user opens URL → poll
Remove a seatConfirm → delete_account (irreversible)

Endpoint refs: disconnect-for-reconnect, reconnect-link, delete-account.

Hard rules

  • Confirm before start_campaign. Never auto-start.
  • Never invent LinkedIn connect — use create_linkedin_connect_link + user browser login.
  • Cursor key ≠ MCP OAuth key.
  • No credit refund on lead/campaign/account delete.
  • Prefer get_setup_status over guessing whether the workspace is ready.

Soft launch

/api-mcp and Help link to this runbook for a one-prompt example.