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: add accounts, start warmup, check health, draft campaigns. 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 connect by signing in from your client and choosing an access level; the connection maps to your workspace and nothing else.

Quick start

  1. 1Add the server to your client: claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp
  2. 2On first use your browser opens. Sign up or sign in, pick what the agent may do and press Allow. No token to copy.
  3. 3Ask your assistant: “how are my accounts doing?” or paste login data to onboard.

Sign in or use a token

Clients that support MCP sign-in (OAuth 2.1 with PKCE, found from the server's 401 answer) need nothing else: the browser opens and you approve the connection. For a client without sign-in, create a token in Settings → AI agents. It is shown once and starts with iom_. Revoke a connection or a token from the same screen; the client loses access at once.

Connect a client

Server URL: https://instaoutreach.com/mcp · transport HTTP · auth OAuth sign-in or a Bearer token.

Claude Code

claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp

Cursor / Claude Desktop (mcp.json)

{ "mcpServers": { "instaoutreach": { "url": "https://instaoutreach.com/mcp" } } }

Client without sign-in

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

Setting up with an AI agent? Point it at https://instaoutreach.com/agents.md.

Tools reference

Every level

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.

Build or Build and send

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

pause_account

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

params: username*

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

Build and send only

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

bind_proxy

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

params: username*, proxy_label*

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

Access levels & safety

Read only read

See stats, leads and replies.

Build build

Also add leads and draft campaigns. Nothing is sent.

Build and send send

Also start and pause sending, within your safety limits.

You pick the level when you approve the connection; Build is the default. Older operator tokens count as Build and send.

  • Tokens are scoped to your organization. The server finds the workspace from the token, so a client can never act on another one.
  • Read tools never return passwords or 2FA secrets.
  • Every change made by an agent 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.
  • Warm-up is off by default: DMs run at your daily limit from day one. Set warm-up days per account if you want a ramp for a brand-new account. 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?
Add the account taylor_demo and start warmup
Start warmup on every account still marked new
Which accounts are still warming up?
Create a draft campaign called “Spring” targeting candle buyers

Troubleshooting

401 unauthorized
Not signed in, or the connection was revoked. Run /mcp in Claude Code (or reconnect in your client) and sign in again.
“Needs a higher access level”
The tool is above the level you approved. Revoke the connection in Settings → AI agents, connect again and pick Build or Build and send.
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?