AI agents (MCP)
Run InstaVision from your AI agent
InstaVision's MCP server lets your AI agent find Instagram creators and leads for you: plan a search, estimate its cost, launch it with your API key and read the results. Runs it starts appear in your Runs list and spend your credits.
No key yet? The server answers list_playbooks and estimate_credits without one, so a remote client can plan and price a search before you create a key.
What your agent can do
Plan
No API key needed.
list_playbooksLists the search playbooks: what each one is for, the fields it takes and its credit range.
estimate_creditsEstimates what a run would cost, without launching anything or spending a credit.
Launch
Spends your credits.
launch_discoveryStarts a run with a credit cap, the most the run may spend. Its MCP annotations mark it as destructive, so your client can ask you before each launch.
Follow and collect
Your runs, as they finish.
get_run_statusReports a run's progress (queued, running, succeeded, failed or aborted) with its counts and the credits charged.
get_run_resultsReturns the accounts a run found, page by page, filtered by email, follower range, category or relevance.
export_run_pdfTurns a run's results into a PDF and returns a download link that expires after 1 hour (or the file itself, when storage is unavailable).
Skip what you've seen
By default, runs skip accounts already delivered to you; a list you ask to enrich is scanned in full.
get_seen_accountsLists the accounts already delivered to you or on your blocklist.
add_seen_accountsAdds handles to your blocklist so later runs skip them.
reset_seen_accountsClears your blocklist, or your whole history of delivered accounts. It is marked as destructive and needs confirm=true.
Connect your agent
Clients that can send a header connect straight to the endpoint. Claude Desktop goes through a small local bridge, npx -y instavision-mcp.
- Endpoint
https://instavision.co/api/mcp/mcp(Streamable HTTP)- Header
Authorization: Bearer <your API key>- Or
X-API-Key: <your API key>if your client can't set the Authorization header
Paste into a terminal (bash or zsh) and press Enter. It then waits for your key: paste it and press Enter. The key isn't shown or saved to your shell history; Claude Code stores it in ~/.claude.json and makes the server available in every project.
read -rs INSTAVISION_API_KEY && claude mcp add --scope user --transport http instavision https://instavision.co/api/mcp/mcp --header "Authorization: Bearer $INSTAVISION_API_KEY"
Add to ~/.cursor/mcp.json, then restart Cursor. It reads the key from the INSTAVISION_API_KEY environment variable, so set that in the environment it starts from.
{"mcpServers":{"instavision":{"url":"https://instavision.co/api/mcp/mcp","headers":{"Authorization":"Bearer ${env:INSTAVISION_API_KEY}"}}}}Run in a terminal. It reads the key from the INSTAVISION_API_KEY environment variable, so set that in the environment it starts from.
codex mcp add instavision --url https://instavision.co/api/mcp/mcp --bearer-token-env-var INSTAVISION_API_KEY
Add to .vscode/mcp.json in your workspace. VS Code asks for the key once, when the server starts, and stores it for later.
{
"inputs": [
{
"type": "promptString",
"id": "instavision-api-key",
"description": "InstaVision API key",
"password": true
}
],
"servers": {
"instavision": {
"type": "http",
"url": "https://instavision.co/api/mcp/mcp",
"headers": { "Authorization": "Bearer ${input:instavision-api-key}" }
}
}
}Settings → Developer → Edit Config, add the block below with your key in place of iv_sk_..., then restart Claude Desktop. It runs the npx bridge, which needs Node.js.
{
"mcpServers": {
"instavision": {
"command": "npx",
"args": ["-y", "instavision-mcp"],
"env": { "INSTAVISION_API_KEY": "iv_sk_..." }
}
}
}On Windows, if npx fails to launch, use "command": "cmd" with "args": ["/c", "npx", "-y", "instavision-mcp"].
| Client | How it connects |
|---|---|
| Claude Code | Remote, with your key in a header |
| Cursor | Remote, with your key in a header |
| Codex | Remote, with your key in a header |
| VS Code | Remote, with your key in a header |
| Claude Desktop | Through the instavision-mcp npx bridge (needs Node.js) |
| claude.ai and ChatGPT | Not yet: they sign in to MCP servers with OAuth, which InstaVision doesn't offer yet |
Things to ask
- “Find forex educators on Instagram who mention mentorship in their bio. Tell me what it will cost before you launch anything.”
- “Find yoga teachers and studios in Lisbon, Portugal, and give me the ones with a public email.”
- “Find more accounts like these: <paste a few handles>. Skip anyone I've already seen, then export the results as a PDF.”
Cost and safety
1 credit = 1 profile scanned
Runs your agent starts spend the credits of the account the key was created in: your own, or a team's.
You agree the cap
estimate_credits prices a run without spending anything, and launch_discovery's own description tells your agent that it spends real money and to agree the credit cap with you before launching. The cap is the most the run may spend, and a launch without one is refused.
Hard limits
An agent's launch can hold at most 500 credits. An agent can't launch while 5 runs of the same account are queued or running, website runs included. Agent launches may commit at most 2,000 credits per account in any 24 hours, counting their caps whatever they end up spending; launches from the website don't count toward it.
Short-lived links
PDF download links expire after 1 hour.
Revoke at any time
Revoke a key under Settings → API & MCP and the next request with it is refused. Runs it already started keep running.
Public data, untrusted text
InstaVision reads public Instagram profiles, never private accounts. Bios, names and captions are written by other people, and the tool that returns them tells your agent to treat them as data, never as instructions.
Questions
Do I need an API key?
To launch runs and read results, yes: create one under Settings → API & MCP (it is shown once). The server answers list_playbooks and estimate_credits without a key, so a remote client can plan and price a search before you have one.
What does a run cost?
1 credit = 1 profile scanned. Every launch carries a credit cap, the most the run may spend, and a launch from an agent can set it to at most 500 credits.
Can I connect from claude.ai or ChatGPT?
Not yet. claude.ai and ChatGPT sign in to remote MCP servers with OAuth, which InstaVision doesn't offer yet. Claude Code, Cursor, Codex and VS Code connect with your API key in a header, and Claude Desktop through the npx bridge.
How do I cut an agent off?
Revoke its key under Settings → API & MCP. The next request with that key is refused; runs it already started keep running.
Will my agent get accounts I've already seen?
Not by default: runs skip accounts already delivered to you, and always skip accounts on your blocklist (a list you ask to enrich is scanned in full). To include accounts you've already received, your agent can launch with excludeSeen set to false; reset_seen_accounts clears the blocklist.
InstaVision is an independent product, not affiliated with or endorsed by Instagram or Meta.