instaoutreach docs
Model Context Protocol

Run your fleet from Claude Code

Connect instaoutreach to Claude Code, Cursor, or any MCP client and manage Instagram accounts by chat — onboard accounts, start warmup, bind proxies, check health. Every limit is enforced server-side; clients can't bypass the anti-ban gates.

What is this

MCP (Model Context Protocol) is an open standard that lets AI clients discover and call tools on a server. instaoutreach exposes a hosted MCP server, so your AI assistant becomes a power-console for your outreach fleet. You authenticate with a token you mint in the app; it maps to your organization and nothing else.

Quick start

  1. 1In the app go to Settings → MCP access and create a token (pick read-only or operator).
  2. 2Add the server to your client with the one-line command shown next to the token.
  3. 3Ask your assistant: “how are my accounts doing?” or paste login data to onboard.

Get a token

Tokens are minted in Settings → MCP access and shown once. They start with iom_. Revoke any token instantly from the same screen; clients using it lose access immediately. Choose the smallest scope you need.

Connect a client

Server URL: https://instaoutreach.com/mcp · transport HTTP · auth Bearer token.

Claude Code

claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp \ --header "Authorization: Bearer iom_your_token_here"

Cursor / Claude Desktop (mcp.json)

{ "mcpServers": { "instaoutreach": { "url": "https://instaoutreach.com/mcp", "headers": { "Authorization": "Bearer iom_your_token_here" } } } }

Tools reference

read-only & operator

list_accounts

List every sending account in your org with status, platform, warmup day, health, proxy and login state.

get_account

Full detail for one account by username (never returns the password or 2FA secret).

params: username*

list_proxies

List proxies in your org with status, geo and whether each is in use.

operator only

onboard_account

Add a sending account. NOTE: for security, credentials (password + 2FA) are NEVER accepted over MCP — they would pass through the AI model. This returns a link to add the account securely via the dashboard's paste flow.

params: username*

enroll_lead

Enroll an Instagram handle into outreach (campaign 'Sirius leads' by default). Pass external_ref = a CRM lead id to link it, so funnel status (queued/dm_sent/replied/booking) writes back to that lead.

params: ig_username*, external_ref, campaign

start_warmup

Start (or resume) the warmup ramp for an account.

params: username*

mark_warmed

Skip warmup: mark an already-aged, actively-used account as active so it can DM immediately. Not for cold accounts.

params: username*

set_warmup_config

Set an account's warmup window (warmup_days_to_dm, days before first DM; 0 = already warm) and/or daily DM limit (max 75). Usage simulation always runs regardless.

params: username*, warmup_days_to_dm, daily_dm_limit

pause_account

Pause an account (stops all engine activity for it).

params: username*

bind_proxy

Bind an existing proxy (by label) to an account.

params: username*, proxy_label*

add_proxy

Add a proxy to your org.

params: label*, host*, port*, username, password, scheme, geo

set_order_meta

Save the purchase order number / source link for an account.

params: username*, order_number, purchase_url

create_campaign

Create a DRAFT (paused) campaign. Never auto-sends — you launch it from the dashboard.

params: name*, offer, dm_prompt, engagement_action

* required. Destructive actions (delete account, change billing) are intentionally not exposed over MCP.

Scopes & safety

read-only

View accounts, proxies and health. Cannot change anything. Safe for dashboards and monitoring.

operator

Everything read-only plus onboarding, warmup, proxy and campaign-draft actions. Never deletes data.

  • Tokens are scoped to your organization. The server resolves the org from the token — a client can never act on another tenant.
  • Read tools never return passwords or 2FA secrets.
  • Every operator action is written to an audit log.

Limits & abuse prevention

The MCP server is a thin layer over the same engine the dashboard uses, so all guardrails apply regardless of caller:

  • Rate limit: 120 calls/min per token.
  • Seat limits and plan entitlements enforced server-side — onboarding past your plan is refused.
  • Warmup gating: a per-account window (default 14 days, set it yourself; 0 for already-warm accounts) before the first DM. There is no “mass-DM” tool.
  • Usage simulation (feed, likes, stories) runs continuously — before, during and after DMing — to keep accounts looking human.
  • Per-account daily DM limit (you set it, hard cap 75) and an abuse circuit-breaker stay in force.

Example prompts

How are my accounts doing? Anything unhealthy?
Onboard taylor_demo:hunter2pass:JBSWY3DPEHPK3PXP with a PL proxy and start warmup
Start warmup on every account still marked new
Which accounts have no proxy bound?
Create a draft campaign called “Spring” targeting candle buyers

Troubleshooting

401 unauthorized
Token missing, mistyped, or revoked. Mint a new one in Settings and update your client header.
“This token is read-only”
The action needs an operator token. Create one with operator scope.
429 rate limited
You exceeded 120 calls/min. Wait a moment and retry.
“seat limit reached”
Add seats in Billing before onboarding more accounts.
Need help?