Post to Instagram via MCP

Quick navigation: Which path should I use? · Multi-platform example · Recovery playbook · All 9 platforms at a glance This page covers everything an AI agent needs to post to Instagram through the VoxBurst MCP server — from finding the right account to recovering from failures. No cross-referencing required.

The complete flow

list_accounts()

[
  { "id": "acc_instagram_abc123", "platform": "instagram", "username": "mybrand", "displayName": "My Brand", "connected": true },
  { "id": "acc_twitter_xyz456", "platform": "twitter", "username": "mybrand_x", "displayName": "My Brand X", "connected": true }
]

validate_content(
  content: "Your caption text here",
  platforms: ["INSTAGRAM"]
)

{
  "valid": true,
  "platforms": {
    "INSTAGRAM": {
      "valid": true,
      "errors": [],
      "warnings": [
        { "code": "NO_MEDIA", "message": "Instagram feed posts require at least one image or video" }
      ]
    }
  }
}

get_post(postId: "post_abc123")

{
  "id": "post_abc123",
  "status": "published",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostUrl": "https://www.instagram.com/p/ABC123/",
      "publishedAt": "2026-06-01T15:00:05Z",
      "error": null
    }
  ]
}

What type of post do you want?

Use this decision guide to pick the right contentType and media setup:

Media input options:

• mediaUrls — public HTTPS image/video URLs (auto-registered with VoxBurst). No local file paths.
• mediaIds — VoxBurst media IDs if you uploaded files via POST /v1/media/upload first.

Post type examples

Single image

create_post(
  content: "Behind the scenes 📸",
  accountIds: ["acc_instagram_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/photo.jpg"]
)

Carousel (2–10 images or videos)

create_post(
  content: "Swipe to see more →",
  accountIds: ["acc_instagram_abc123"],
  contentType: "CAROUSEL",
  mediaUrls: [
    "https://cdn.example.com/slide-1.jpg",
    "https://cdn.example.com/slide-2.jpg",
    "https://cdn.example.com/slide-3.jpg"
  ]
)

Reel

create_post(
  content: "Our latest drop 🔥",
  accountIds: ["acc_instagram_abc123"],
  contentType: "REEL",
  mediaUrls: ["https://cdn.example.com/reel.mp4"]
)

Scheduled post

create_post(
  content: "Launch day. Shipping now.",
  accountIds: ["acc_instagram_abc123"],
  contentType: "CAROUSEL",
  mediaUrls: [
    "https://cdn.example.com/launch-1.jpg",
    "https://cdn.example.com/launch-2.jpg"
  ],
  scheduledFor: "2026-06-01T15:00:00Z"
)

Post with first comment and delay

create_post(
  content: "New product just dropped.",
  accountIds: ["acc_instagram_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/product.jpg"],
  firstComment: "Shop the link in bio 👆 #newdrop #launch",
  firstCommentDelay: 30
)

firstCommentDelay is in seconds. The comment posts 30 seconds after the photo publishes.

Save as draft

create_post(
  content: "Draft caption — needs review.",
  accountIds: ["acc_instagram_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/photo.jpg"],
  saveAsDraft: true
)

Tell your AI agent this

Copy any of these prompts directly to Claude, Cursor, or any MCP-capable assistant. Replace the bracketed values with your own.

Single image, post now:

Post to Instagram account [acc_id]. Caption: [your caption]. Media URL: [https://...]. Content type: IMAGE. Timing: post now.

Carousel, scheduled:

Post to Instagram account [acc_id]. Caption: [your caption]. Media URLs: [url1], [url2], [url3]. Content type: CAROUSEL. Timing: schedule [2026-06-01T15:00:00Z].

Reel with first comment:

Post a Reel to Instagram account [acc_id]. Caption: [your caption]. Media URL: [https://...video.mp4]. Content type: REEL. First comment: [hashtags or CTA]. First comment delay: 30 seconds.

Save as draft for review:

Create a draft Instagram post on account [acc_id]. Caption: [your caption]. Media URL: [https://...]. Content type: IMAGE. Save as draft — do not publish.

Validate before posting:

Before posting to Instagram account [acc_id], validate this caption: [your caption text]. Report any errors or warnings.

End-to-end narrative example

Here is exactly what happens when an agent posts a carousel to Instagram:

User says:

“Post our product launch carousel to Instagram. Use these three images: https://cdn.example.com/a.jpg , b.jpg, c.jpg. Caption: ‘Three ways to use the new product 🎯’. Schedule for tomorrow at 3 PM UTC. Add a first comment 30 seconds after it goes live: ‘Link in bio for full details.’”

Agent calls list_accounts() → finds acc_instagram_abc123 with platform: instagram.

Agent calls validate_content() with the caption and platforms: ["INSTAGRAM"] → returns valid: true, no errors.

Agent calls create_post():

{
  "content": "Three ways to use the new product 🎯",
  "accountIds": ["acc_instagram_abc123"],
  "contentType": "CAROUSEL",
  "mediaUrls": [
    "https://cdn.example.com/a.jpg",
    "https://cdn.example.com/b.jpg",
    "https://cdn.example.com/c.jpg"
  ],
  "scheduledFor": "2026-06-02T15:00:00Z",
  "firstComment": "Link in bio for full details.",
  "firstCommentDelay": 30
}

VoxBurst responds:

{
  "id": "post_xyz789",
  "status": "scheduled",
  "scheduledFor": "2026-06-02T15:00:00Z",
  "platforms": [
    { "platform": "instagram", "status": "pending" }
  ]
}

Agent reports to user: “Carousel scheduled for June 2 at 3 PM UTC (post ID: post_xyz789). A first comment will be added 30 seconds after it publishes.”

Common failures and how to recover

Recovering a failed post

retry_post(postId: "post_abc123")

If the platform has exhausted automatic retries (3 attempts), use get_post to read the error, fix the underlying issue (e.g. wrong media), then call the REST /v1/posts/:id/platforms/:platformId/fix endpoint with corrected media.

Field reference

Quick reference for Instagram-specific fields in create_post:

Account requirements

When Instagram is a poor fit

• Text-only posts — Instagram requires at least one image or video on every feed post
• Stories — the Graph API does not allow third-party Story publishing
• Link-in-post CTAs — Instagram does not make links clickable in captions; use first comment or bio link instead
• Long-form articles — Instagram caps captions at 2,200 characters; use LinkedIn or Facebook for long-form
• Personal accounts — API access requires a Business or Creator account; personal profiles cannot be connected

Cross-platform override example

When posting to multiple platforms at once, use platformOverrides to give Instagram a visual-first caption while other platforms get different text:

create_post(
  content: "Announcing our new feature today.",
  accountIds: ["acc_instagram_abc", "acc_twitter_def", "acc_linkedin_ghi"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/feature.jpg"],
  platformOverrides: {
    "INSTAGRAM": {
      "content": "The new feature is here. Swipe to see what changed 👆"
    },
    "TWITTER": {
      "content": "New feature just dropped 🚀 #launch #product"
    },
    "LINKEDIN": {
      "content": "Excited to share our latest feature — built based on direct user feedback. Here is what changed and why."
    }
  },
  firstComment: "#newfeature #productupdate"
)

See the same post across all platforms guide for a full 8-platform example.

Benchmark checklist

Last updated: 2026-05-31 — Added JSON tool-call examples, benchmark checklist, and expanded platform guide.