Post to Facebook via MCP

Quick navigation: Which path should I use? · Multi-platform example · Recovery playbook · All 9 platforms at a glance

Prerequisites: VoxBurst MCP server configured. See MCP Server setup.

VoxBurst posts to Facebook Pages only. Personal profile posting is limited by the Facebook Graph API. The connected account must be an Admin or Editor of the Page.

The complete flow

Find the Facebook account ID


list_accounts()

Look for "platform": "facebook". If you see multiple Facebook accounts, identify the one linked to your Page — the displayName will show the Page name.

Optionally validate content first


validate_content(
  content: "Your Facebook post text",
  platforms: ["FACEBOOK"]
)

Create the post

See post type examples below.

Check the result


get_post(postId: "post_abc123")


{
  "id": "post_abc123",
  "status": "published",
  "platforms": [
    {
      "platform": "facebook",
      "status": "published",
      "platformPostUrl": "https://www.facebook.com/mybrandpage/posts/1234567890",
      "publishedAt": "2026-06-01T12:00:05Z",
      "error": null
    }
  ]
}

What type of post do you want?

I want to post…	contentType	Media required?	Notes
Text only	`TEXT`	No	Max 63,206 chars
Image(s)	`IMAGE`	Yes — 1–10 images
A video	`VIDEO`	Yes — 1 video	Max 4 hours

Facebook Reels, carousels (as a distinct contentType), and Stories are not currently supported through the Graph API posting flow.

Media input options:

mediaUrls — public HTTPS image/video URLs (auto-registered)
mediaIds — VoxBurst media IDs from prior uploads

Post type examples

Text post


create_post(
  content: "We are hiring! Three open engineering roles — apply at https://careers.example.com. If you know someone great, please share this post.",
  accountIds: ["acc_facebook_abc123"],
  contentType: "TEXT"
)

First comment on Facebook — coming soon. First-comment posting requires a Meta API permission (pages_manage_engagement) that is currently pending approval. Until approval is granted, any firstComment value is silently skipped on Facebook — the post itself publishes normally. Include the link directly in the post body in the meantime.

Image post


create_post(
  content: "Behind the scenes from our product launch event last night 📸",
  accountIds: ["acc_facebook_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/event-photo.jpg"]
)

Multiple images


create_post(
  content: "Highlights from the summit. Three days, 400 attendees, and too many great conversations to count.",
  accountIds: ["acc_facebook_abc123"],
  contentType: "IMAGE",
  mediaUrls: [
    "https://cdn.example.com/summit-1.jpg",
    "https://cdn.example.com/summit-2.jpg",
    "https://cdn.example.com/summit-3.jpg"
  ]
)

Video post


create_post(
  content: "Our founder shares the story behind the product — 4 minutes, worth your time.",
  accountIds: ["acc_facebook_abc123"],
  contentType: "VIDEO",
  mediaIds: ["media_founder_story_abc123"]
)

Scheduled post


create_post(
  content: "Happy Friday! Here is a look at what the team shipped this week.",
  accountIds: ["acc_facebook_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/weekly-recap.jpg"],
  scheduledFor: "2026-06-06T16:00:00Z"
)

Tell your AI agent this

Text post, post now:

Post to Facebook Page account [acc_id]. Content: [your post text]. Post now.

Image, scheduled:

Post to Facebook account [acc_id]. Content: [text]. Attach image: [https://...]. Schedule for [ISO timestamp].

Video post:

Post a video to Facebook account [acc_id]. Caption: [text]. Use media ID [media_id].

Failure cookbook

Error	Cause	Fix
`PAGE_NOT_SELECTED`	Account connected but no Page chosen	Call `POST /v1/accounts/:id/select-page` in the REST API
`INSUFFICIENT_PERMISSIONS`	Missing `pages_manage_posts` or `publish_pages` scope	Re-connect the Facebook account and approve all required permissions
`OAUTH_TOKEN_EXPIRED`	Long-lived token expired (60–90 days)	Re-connect the account; VoxBurst will request a fresh token
`VIDEO_TOO_LARGE`	Video over 10 GB	Compress or trim the video
`CONTENT_TOO_LONG`	Over 63,206 chars (rare)	Shorten the text
`DUPLICATE_POST`	Facebook detected identical recent content	Vary the caption slightly
`PAGE_RESTRICTED`	Page has policy violations or is restricted	Check Facebook Business Suite for Page status
Post status `failed`	Various Graph API errors	Read `platforms[].error`; call `retry_post` for transient failures

Account requirements

Requirement	Detail
Account type	Facebook Page (not a personal profile)
Auth method	OAuth 2.0 via Facebook Graph API
Key precondition	A Page must be selected after connecting — call `POST /v1/accounts/:id/select-page` if not already configured
Re-connect trigger	Token expires after ~60–90 days; `OAUTH_TOKEN_EXPIRED` signals re-connect needed

When Facebook is a poor fit

Personal profile publishing — the Graph API has very limited personal profile posting access; use a Page
Reels or short-form video — Facebook Reels are not currently supported through the posting flow
Carousel posts — CAROUSEL is not a supported contentType for Facebook through VoxBurst
Content where link clicks matter most — Facebook de-prioritizes posts with external links in organic reach; first-comment posting (which can help with this) is pending Meta API approval and not yet available

Cross-platform override example

Facebook can take a longer, more casual caption while Twitter needs a shorter one:


create_post(
  content: "New update available for all users.",
  accountIds: ["acc_facebook_jkl", "acc_twitter_def", "acc_instagram_abc"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/update-banner.jpg"],
  platformOverrides: {
    "FACEBOOK": {
      "content": "We just pushed a major update. Here is everything that changed — and a few features our community asked for by name. Full changelog: https://voxburst.io/changelog"
    },
    "TWITTER": {
      "content": "Major update just dropped. Everything changed for the better 🔧 #update"
    },
    "INSTAGRAM": {
      "firstComment": "Full changelog: https://voxburst.io/changelog"
    }
  }
)

firstComment works on Instagram in this multi-platform example. Facebook first-comment support is pending Meta API approval — include important links in the Facebook post body directly for now.

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

Benchmark checklist

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


Supported content types	`TEXT`, `IMAGE` (1–10), `VIDEO`
Unsupported content types	`CAROUSEL`, `REEL`, `STORY`
Validation gotcha	Posts go to a Facebook Page — personal profiles have limited API access
Media gotcha	Video max 10 GB; H.264 recommended
Account gotcha	Page must be selected via `POST /v1/accounts/:id/select-page` if not already set
Example prompt	”Post to Facebook Page account acc_id. Content: text. Attach image: url.”
Example tool call	`create_post(content: "...", accountIds: ["acc_facebook_abc"], contentType: "IMAGE", mediaUrls: ["https://..."])`
Example response	`{ "status": "published", "platforms": [{ "platform": "facebook", "platformPostUrl": "https://www.facebook.com/..." }] }`
Recovery path	`retry_post` for transient errors; re-connect account for OAuth token failures