MCP Tools Reference - Postzee Docs

Complete reference for all 25 tools exposed by Postzee’s MCP server. These tools are available to any MCP-compatible AI agent (Claude Code, OpenClaw, Hermes Agent, or direct MCP clients).

All tools accept the API key embedded in your MCP URL. They are scoped to a single organization. Costs for AI generation are always returned in credits, never in USD. ($1 USD = 1,000 credits.)

Quick reference

Category	Tools
Context & Discovery	`POSTZEE_GET_CONTEXT`, `POSTZEE_LIST_PLANS`, `POSTZEE_LIST_CREDIT_PACKAGES`
Models & Specs	`POSTZEE_LIST_MODELS_DETAILED`, `POSTZEE_LIST_PLATFORM_SPECS`, `POSTZEE_GET_BEST_POSTING_TIMES`
Cost & Validation	`POSTZEE_ESTIMATE_GENERATION_COST`, `POSTZEE_VALIDATE_GENERATION`
Channels & Credits	`POSTZEE_LIST_CHANNELS`, `POSTZEE_GET_CREDITS`
Media Memory	`POSTZEE_LIST_MEDIA`, `POSTZEE_UPLOAD_MEDIA`
Prompt Enhancement	`POSTZEE_ENHANCE_PROMPT`
Generation	`POSTZEE_GENERATE_IMAGE`, `POSTZEE_GENERATE_VIDEO`, `POSTZEE_CHECK_JOB`
Images & Carousels	`POSTZEE_RENDER_IMAGE`, `POSTZEE_RENDER_CAROUSEL`, `POSTZEE_REPLACE_CAROUSEL_SLIDE`, `POSTZEE_APPEND_CAROUSEL_SLIDE`
HeyGen	`POSTZEE_LIST_HEYGEN_AVATARS`, `POSTZEE_LIST_HEYGEN_VOICES`, `POSTZEE_GENERATE_HEYGEN_VIDEO`
Posting	`POSTZEE_CREATE_POST`, `POSTZEE_GET_POST`
Legacy (deprecated)	`POSTZEE_LIST_IMAGE_MODELS`, `POSTZEE_LIST_VIDEO_MODELS`

Context & Discovery

POSTZEE_GET_CONTEXT

Single-shot context aggregation. Recommended first call of every session. Returns plan, credits, storage, channels, features, and skill version in one round-trip. Parameters: None Returns:

{
  "skill": {
    "currentVersion": "4.0.0",
    "repoUrl": "https://github.com/Zee-Labs/postzee-skill",
    "downloadUrl": "https://github.com/Zee-Labs/postzee-skill/releases/latest/download/postzee-skill.zip",
    "releaseNotesUrl": "https://github.com/Zee-Labs/postzee-skill/releases/latest"
  },
  "plan": {
    "tier": "FREE | STANDARD | TEAM | PRO | ULTIMATE",
    "isLifetime": false,
    "period": "MONTHLY | YEARLY | null",
    "cancelAt": "string | null",
    "canPost": true,
    "canConnectChannels": true,
    "canUseAi": true,
    "channelsLimit": 5,
    "postsPerMonth": 400,
    "postsRemaining": 380,
    "monthlyCredits": 2000,
    "storageLimitGB": 15,
    "monthPriceUSD": 27,
    "yearPriceUSD": 252
  },
  "credits": {
    "available": 4500,
    "monthly": 2000,
    "purchased": 2500,
    "used": 0,
    "lastResetAt": "2026-04-15T10:00:00Z",
    "nextResetAt": "2026-05-15T10:00:00Z"
  },
  "storage": { "usedGB": 1.2, "limitGB": 15, "percentUsed": 8 },
  "channels": {
    "connected": 5,
    "active": 4,
    "requiresReauth": 1,
    "disabled": 0,
    "withIssues": 1
  },
  "organization": { "id": "...", "timezone": "America/Sao_Paulo" },
  "features": {
    "img2vid": true,
    "veoR2V": false,
    "soraStoryboard": false,
    "sora1080p": true,
    "audioControl": true,
    "firstLastFrame": true,
    "firstLastFrameProvider": "wan-flf2v",
    "heygen": true
  }
}

features.* flags reflect what the MCP can drive right now — agents should only suggest features where the corresponding flag is true.

POSTZEE_LIST_PLANS

List the 5 subscription tiers with pricing and limits. Parameters: None Returns:

[
  {
    "tier": "STANDARD",
    "monthPriceUSD": 27,
    "yearPriceUSD": 252,
    "yearMonthlyDisplayUSD": 21,
    "channelsLimit": 5,
    "postsPerMonth": 400,
    "postsUnlimited": false,
    "monthlyCredits": 2000,
    "storageLimitGB": 15,
    "canPost": true,
    "canUseAi": true,
    "teamMembers": false,
    "publicApi": true,
    "webhooks": 2
  }
]

POSTZEE_LIST_CREDIT_PACKAGES

List one-time credit packages (eternal — never expire). Parameters: None Returns:

[
  { "id": "starter", "name": "Starter", "priceUSD": 2, "credits": 2000, "popular": false },
  { "id": "basic", "name": "Basic", "priceUSD": 10, "credits": 10000, "popular": false },
  { "id": "standard", "name": "Standard", "priceUSD": 25, "credits": 25000, "popular": true },
  { "id": "pro", "name": "Pro", "priceUSD": 50, "credits": 50000, "popular": false },
  { "id": "enterprise", "name": "Enterprise", "priceUSD": 100, "credits": 100000, "popular": false }
]

Models & Specs

POSTZEE_LIST_MODELS_DETAILED

Capability matrix for all available image and video models — durations, resolutions, audio capabilities, accepted custom params, and a relative cost tier. Parameters:

Parameter	Type	Required	Description
`type`	string	No	`"image"`, `"video"`, or `"all"` (default)
`includeHeygen`	boolean	No	Include the synthetic HeyGen entry. Default: `true`
`family`	string	No	Filter to a single family (e.g. `"ideogram-v3"`, `"sora-2"`, `"veo3.1"`)
`agenticDefault`	boolean	No	When `true`, return only entries flagged as the recommended pick for automation

Returns (per model):

{
  "modelId": "sora-2-t2v-pro-1080p",
  "displayName": "Sora 2 Pro 1080p (Text-to-Video)",
  "type": "video",
  "family": "sora-2-pro",
  "tierWithinFamily": "premium",
  "audio": "speech-lipsync",
  "supportsImg2Img": false,
  "supportsImg2Vid": false,
  "supportsVector": false,
  "durations": [10, 15],
  "resolutions": ["1080p"],
  "aspectRatios": ["16:9", "9:16"],
  "recommendedAspectsByPlatform": {
    "instagram_reels": "9:16",
    "tiktok_feed": "9:16",
    "youtube_feed": "16:9"
  },
  "customParamsAccepted": {
    "duration": { "type": "enum", "enum": [10, 15], "description": "..." }
  },
  "costTier": "premium",
  "popular": false,
  "agenticDefault": false,
  "agenticDefaultFree": false,
  "bestFor": ["highest cinematic quality", "1080p Pro", "final publication"],
  "notRecommendedFor": ["high-volume automation"]
}

costTier is one of very-low, low, mid, high, premium — the absolute credit cost is intentionally not exposed; use POSTZEE_ESTIMATE_GENERATION_COST instead. The synthetic heygen-avatar-video entry has costTier: "external" and a billingNote indicating that HeyGen bills on the user’s HeyGen account, not Postzee credits.

POSTZEE_LIST_PLATFORM_SPECS

Per-platform specs (aspect ratios, max slides for carousels, caption character limits, hashtag recommendations). Parameters:

Parameter	Type	Required	Description
`platforms`	string[]	No	Filter to specific platforms (e.g. `["instagram", "tiktok"]`). Omit for all.

Covered platforms: instagram, facebook, linkedin, x, tiktok, youtube, pinterest, threads, bluesky, reddit.

POSTZEE_GET_BEST_POSTING_TIMES

Curated heuristic best-posting-time windows per channel, returned in the organization’s timezone. Parameters:

Parameter	Type	Required	Description
`channelIds`	string[]	No	Filter to specific channels. Omit for all active channels.

Returns:

[
  {
    "channelId": "...",
    "platform": "instagram",
    "name": "My Instagram",
    "timezone": "America/Sao_Paulo",
    "bestTimes": [
      { "time": "11:00", "timezone": "America/Sao_Paulo", "nextDateLocal": "2026-05-06", "score": 90, "reason": "Lunchtime peak", "source": "heuristic" },
      { "time": "19:00", "timezone": "America/Sao_Paulo", "nextDateLocal": "2026-05-06", "score": 95, "reason": "Evening prime", "source": "heuristic" }
    ]
  }
]

Channels with disabled or requiresReauth status are filtered out — recommendations are only returned for channels that can actually post.

Cost & Validation

POSTZEE_ESTIMATE_GENERATION_COST

Single source of truth for cost estimates. Always returns credits, never USD. Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"image"` or `"video"`
`model`	string	Yes	Model id from `POSTZEE_LIST_MODELS_DETAILED`
`duration`	number	No	Seconds (video, for per-second-priced models)
`resolution`	string	No	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"`
`quality`	string	No	Sora 2 Pro: `"standard"` (720p) or `"high"` (1080p)
`generateAudio`	boolean	No	Affects cost on Veo, Pixverse, Wan 2.5
`voiceControl`	boolean	No	Kling 2.6/3.0 Pro
`aspectRatio`	string	No	Informational

Returns:

{
  "modelId": "sora-2-t2v-pro",
  "displayName": "Sora 2 Pro Text-to-Video",
  "estimatedCredits": 5000,
  "currentBalance": 4500,
  "willExceedBalance": true,
  "creditsAfter": 0,
  "shortfall": 500,
  "warnings": []
}

POSTZEE_VALIDATE_GENERATION

Pre-flight validation — catches param errors, insufficient credits, storage issues, and plan blocks before burning credits. Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"image"` or `"video"`
`model`	string	Yes	Model id
`duration`	number	No	Seconds
`aspectRatio`	string	No	e.g. `"4:5"`
`resolution`	string	No	Output resolution
`quality`	string	No	Sora Pro `"standard"` / `"high"`
`generateAudio`	boolean	No
`voiceControl`	boolean	No
`imageUrl`	string	No	Required for image-to-video models
`slideCount`	number	No	Batch multiplier (e.g., N variations of the same prompt). Not for carousels — those go through `POSTZEE_RENDER_CAROUSEL` with its own cost model.

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": ["Storage at 85% — approaching limit."],
  "estimatedCreditsPerItem": 160,
  "totalEstimatedCredits": 1600,
  "slideCount": 10,
  "currentBalance": 4500,
  "willExceedBalance": false,
  "shortfall": 0
}

When valid: false, the errors[] array contains human-readable problems — e.g. duration not in the model’s allowed set, missing imageUrl for an i2v model, storage 100%, or a model that’s registered but not yet driveable through MCP.

Channels & Credits

POSTZEE_LIST_CHANNELS

List connected social media channels with explicit action flags. Parameters: None Returns:

[
  {
    "id": "channel-uuid",
    "name": "My Instagram",
    "platform": "instagram",
    "picture": "https://...",
    "profile": "https://...",
    "disabled": false,
    "requiresReauth": false,
    "canPostNow": true,
    "actionRequired": "none",
    "actionUrl": null,
    "actionMessage": null,
    "status": "active",
    "statusMessage": null
  }
]

actionRequired is one of "none" (ready to post), "reconnect" (token expired — user reconnects), or "reenable" (admin/billing — user re-enables, not the same as reconnect). statusMessage is a human-readable explanation when the channel requires action (e.g., "Channel token expired. Reconnect to keep posting."). It is null when actionRequired is "none".

POSTZEE_GET_CREDITS

Lightweight credit balance. Subset of POSTZEE_GET_CONTEXT.credits — prefer the latter for new code. Parameters: None Returns:

{
  "available": 4500,
  "monthly": 2000,
  "used": 0,
  "purchased": 2500
}

All values in credits ($1 USD = 1,000 credits).

Media Memory

The two tools below let an agent recall and reuse media assets — both AI-generated and user-uploaded — across turns and across sessions, instead of asking the user to paste URLs again.

POSTZEE_LIST_MEDIA

Recent media list, scoped to the organization. Returns the newest items first. Parameters:

Parameter	Type	Required	Description
`type`	string	No	`"image"`, `"video"`, or `"all"` (default)
`source`	string	No	`"generated"` (AI-created), `"uploaded"` (imported via `POSTZEE_UPLOAD_MEDIA`), or `"all"` (default)
`search`	string	No	Case-insensitive search over the original prompt (AI media) and file name
`since`	string	No	ISO date — only return media created after this instant
`limit`	number	No	Default 20, max 100

Returns (per item):

{
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/abc.jpg",
  "name": "abc.jpg",
  "type": "image",
  "source": "generated",
  "prompt": "dog on the beach at sunset",
  "modelUsed": "ideogram-v3-turbo",
  "createdAt": "2026-05-07T14:23:00Z",
  "sizeBytes": 245678,
  "dimensions": { "width": 1024, "height": 1280 }
}

Returns (failure):

{ "error": "list_media_failed", "message": "..." }

Soft-deleted media is automatically excluded. Media used as a user profile picture is also excluded.

POSTZEE_UPLOAD_MEDIA

Import a public URL into Postzee’s storage. Returns a stable mediaId and CDN URL for reuse across GENERATE_*, CREATE_POST, and LIST_MEDIA calls. Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	Public `http://` or `https://` URL. Must be reachable without authentication.
`description`	string	No	Short label stored alongside the media (helps the agent track its manifest)

Returns (success):

{
  "success": true,
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/uploads/xyz.jpg",
  "type": "image",
  "sizeBytes": 524288,
  "dimensions": { "width": 1080, "height": 1920 }
}

Returns (failure):

{
  "success": false,
  "error": "blocked_url | unsupported_type | size_limit_exceeded | fetch_failed | storage_full | upload_failed | save_failed",
  "message": "..."
}

Validation order (each step rejects before the next):

URL is parseable and uses http/https
Hostname is not localhost / private IP / cloud-metadata endpoint (SSRF defense)
HEAD probe succeeds (or ranged GET fallback)
Content-Type matches the configured allowlist (default: image/jpeg, image/png, image/webp, image/gif / video/mp4, video/quicktime, video/webm)
Size within the per-kind cap (default: 25 MB image, 500 MB video)
Organization storage quota has room

Default upload limits (configurable via SystemConfig):

Kind	Max size	Accepted formats
Image	25 MB	JPG, PNG, WebP, GIF
Video	500 MB	MP4, MOV, WebM

Limits and accepted formats can be tuned at runtime by updating the corresponding UPLOAD_* keys in SystemConfig. Both this MCP tool and the REST upload endpoints share the same source of truth — change once, applies everywhere within ~5 minutes (cache TTL).

For privacy and security, the tool never accepts authentication headers or auth tokens. URLs that require a Bot Token (e.g. Telegram getFile URLs) must be re-hosted by the chat client to a public URL first. For base64 / direct file uploads, use the existing REST /media/upload-server endpoint instead — the MCP tool handles URL imports only.

After a successful import, the media appears in POSTZEE_LIST_MEDIA with source: "uploaded".

Prompt Enhancement

POSTZEE_ENHANCE_PROMPT

Optimize a user prompt for better AI generation results. Free — no credit cost. Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	The user’s prompt to optimize
`mediaType`	string	Yes	`"image"` or `"video"`
`model`	string	No	Target AI model id (for model-specific optimization)
`language`	string	No	Output language code (e.g., `"pt"`, `"es"`, `"fr"`, `"de"`). If omitted, uses the account owner’s language or defaults to English.

Returns:

{ "success": true, "enhancedPrompt": "A young woman in a tailored trench coat walks through..." }

Generation

POSTZEE_GENERATE_IMAGE

Generate an AI image from a text prompt. Async operation — returns a job id to poll with POSTZEE_CHECK_JOB. Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	Detailed image description
`model`	string	Yes	Model id from `POSTZEE_LIST_MODELS_DETAILED` (type `"image"`)
`aspectRatio`	string	No	e.g. `"1:1"`, `"4:5"`, `"9:16"`, `"16:9"`. Default: `"1:1"`
`imageUrls`	string[]	No	Reference image URLs for image-to-image
`quality`	string	No	GPT Image 2: `"low"`, `"medium"`, or `"high"`. Default: `"high"`
`style`	string	No	Recraft V3/V4: `"realistic_image"`, `"digital_illustration"`, `"vector_illustration"`
`renderingSpeed`	string	No	Ideogram V3 tier: `"turbo"`, `"balanced"`, or `"quality"`
`negativePrompt`	string	No	Things to exclude from the image
`seed`	number	No	Optional deterministic seed

Returns (success):

{ "success": true, "jobId": "job-uuid", "status": "processing", "message": "Image generation started..." }

Returns (failure):

{ "success": false, "error": "unsupported_model | unknown_model | wrong_type | organization_not_found | generation_failed", "message": "...", "suggestions": [{ "modelId": "...", "reason": "..." }] }

POSTZEE_GENERATE_VIDEO

Generate an AI video from a text prompt or reference image. Async operation. Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	Detailed video description
`model`	string	Yes	Model id from `POSTZEE_LIST_MODELS_DETAILED` (type `"video"`)
`duration`	number	No	Seconds. Allowed values vary per model — check `model.durations`
`aspectRatio`	string	No	`"16:9"` or `"9:16"`. Default: `"16:9"`
`imageUrl`	string	No	Reference image URL for image-to-video models
`endImageUrl`	string	No	End frame URL for first-last-frame interpolation (e.g. `wan-flf2v`)
`resolution`	string	No	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"` (model-dependent)
`quality`	string	No	Sora 2 Pro only: `"standard"` (720p) or `"high"` (1080p)
`generateAudio`	boolean	No	Generate ambient audio (Veo 3.1, Pixverse, Wan 2.5). Affects credits.
`voiceControl`	boolean	No	Voice control (Kling 2.6/3.0 Pro). Affects credits.
`negativePrompt`	string	No	Things to avoid in the video
`seed`	number	No	Optional deterministic seed

Returns: same shape as POSTZEE_GENERATE_IMAGE.

Tier-specific model ids returned by POSTZEE_LIST_MODELS_DETAILED (e.g. ideogram-v3-turbo, gpt-image-2-high, sora-2-t2v-pro-1080p, recraft-v4-vector) can be passed directly to model. The MCP translates them to the right backend payload automatically — no separate tier or quality param required for tier selection.

A few model ids in the catalog are not yet driveable through MCP and will be rejected upfront (Sora 2 storyboard variants, some Veo 3.1 paths). The error response includes a suggestions[] array with up to three close alternatives — pick one of those.

POSTZEE_CHECK_JOB

Poll the status of an async image or video generation job. Parameters:

Parameter	Type	Required	Description
`jobId`	string	Yes	Job id from `POSTZEE_GENERATE_*`

Returns (processing):

{ "jobId": "...", "status": "processing", "progress": 45 }

Returns (success):

{ "jobId": "...", "status": "success", "progress": 100, "mediaUrl": "https://cdn.postzee.app/...", "mediaId": "media-uuid" }

Returns (failed):

{ "jobId": "...", "status": "failed", "error": "Generation failed: ..." }

Returns (not found):

{ "jobId": "...", "status": "not_found" }

Images & Carousels

The image and carousel pipeline lets the agent compose editorial slides with pixel-perfect typography, consistent fonts, and no hallucinated words. The agent submits the composed slide(s); Postzee renders and returns the final media ready to publish. Four tools cover the lifecycle: a single-image render for standalone posts with editorial typography, a full carousel render for the initial batch, surgical replacement for fixes, and incremental append for iterative authoring.

POSTZEE_RENDER_IMAGE

Render ONE HTML document to a single PNG Media. The single-image counterpart to POSTZEE_RENDER_CAROUSEL, for standalone editorial posts (text-heavy single images, magazine-style covers, hero quote cards) where the value is in the layout + typography rather than in a swipeable sequence. Parameters:

Parameter	Type	Required	Description
`html`	string	Yes	Complete `<!doctype html>` document for the slide. Reference images by their Postzee CDN URL (returned by `POSTZEE_GENERATE_IMAGE` or `POSTZEE_UPLOAD_MEDIA`). Static composition only — no interactive scripts.
`width`	number	No	Output width in px (256-2160). Default `1080`.
`height`	number	No	Output height in px (256-2160). Default `1350` (4:5 — optimized for Instagram feed).
`name`	string	No	Optional title shown in the gallery.

Same hard limits as POSTZEE_RENDER_CAROUSEL: 7 MB max payload, 256-2160 px per dimension, 45 s render timeout. Returns (success):

{
  "success": true,
  "mediaId": "media-uuid",
  "mediaUrl": "https://cdn.postzee.app/...",
  "width": 1080,
  "height": 1350,
  "mediaGroupId": "group-uuid",
  "message": "Image rendered successfully (1080×1350). Use 'mediaUrl' when calling POSTZEE_CREATE_POST."
}

mediaGroupId is exposed for advanced callers but typical use is to pass mediaUrl directly to POSTZEE_CREATE_POST as a single-element mediaUrls array. Returns (failure):

{ "success": false, "error": "render_failed", "message": "..." }

Same idempotency cache as the carousel render: identical payloads inside a 1-hour window return the cached mediaId instead of re-rendering.

POSTZEE_RENDER_CAROUSEL

Render N HTML slides to PNG and atomically group them as one carousel MediaGroup. Synchronous — blocks until all slides finish. Parameters:

Parameter	Type	Required	Description
`slides`	array	Yes	1-15 slide objects in display order. Each: `{ html: string, width?: number, height?: number }`. The array index becomes the slide order.
`aspectRatio`	string	No	Default canvas size when slide width/height are omitted: `"1:1"` (1080×1080), `"4:5"` (1080×1350), `"9:16"` (1080×1920). Default `"1:1"`.
`name`	string	No	Optional title shown in the gallery.

Hard limits enforced server-side:

Max 15 slides per call
Min 256 / max 2160 px per dimension
7 MB max HTML per slide
50 MB max total payload per call (sum of all slides)
45 s timeout per slide

Platform-aware publish guards. Rendering accepts up to 15 slides, but publishing is bound by each social network’s native limit (Instagram/Facebook ≤ 10, LinkedIn ≤ 20, TikTok ≤ 35, Threads/Reddit ≤ 20, Pinterest ≤ 5, X ≤ 4, Bluesky/Mastodon ≤ 4, Telegram/VK ≤ 10). When POSTZEE_CREATE_POST is called with mediaUrls exceeding the destination limit, Postzee rejects the post before calling the platform API, with an error message translated to the user’s language. Call POSTZEE_LIST_PLATFORM_SPECS for the live table. Partial-tolerant failure model. If a slide errors out or the dispatcher times out before all slides settle, the group is preserved with renderStatus: "partial" in aiMetadata (instead of being rolled back). Retry missing slides via POSTZEE_REPLACE_CAROUSEL_SLIDE or POSTZEE_APPEND_CAROUSEL_SLIDE. Slides that DID render are never destroyed — the user keeps their work even on partial failure. Order is structural, not temporal. The array index = orderInGroup, assigned BEFORE any worker runs. Slides may render in parallel but order is preserved deterministically. Security model. Slide compositions are rendered as static content — interactive scripts are inert. Network requests for referenced assets are restricted to public hosts (private/internal addresses are blocked). Returns:

{
  "success": true,
  "mediaGroupId": "uuid",
  "totalSlides": 10,
  "aspectRatio": "4:5",
  "slides": [
    { "mediaId": "...", "url": "https://cdn.postzee.app/.../slide-0.png", "orderInGroup": 0 },
    { "mediaId": "...", "url": "https://cdn.postzee.app/.../slide-1.png", "orderInGroup": 1 }
  ],
  "mediaUrls": [
    "https://cdn.postzee.app/.../slide-0.png",
    "https://cdn.postzee.app/.../slide-1.png"
  ]
}

mediaUrls is already in display order — pass it straight to POSTZEE_CREATE_POST. Failure response:

{ "success": false, "error": "render_failed", "message": "Carousel rendering failed: ..." }

POSTZEE_REPLACE_CAROUSEL_SLIDE

Surgically replace ONE slide in an existing carousel without touching the others. Use when the user says “change slide N” — saves time and credits, and preserves slide identity (other slides keep their URLs and IDs). Parameters:

Parameter	Type	Required	Description
`mediaGroupId`	string	Yes	The id returned by `POSTZEE_RENDER_CAROUSEL`.
`orderInGroup`	number	Yes	Zero-based index of the slide to replace. Slide 4 → `3`. Must point at a non-deleted slide.
`slide`	object	Yes	`{ html, width?, height? }` — same shape as one entry of `RENDER_CAROUSEL.slides`.

The replaced slide is soft-deleted after the new render uploads successfully; the new slide takes the same orderInGroup. If orderInGroup === 0, the carousel’s cover thumbnail is updated automatically. Returns:

{
  "success": true,
  "mediaGroupId": "uuid",
  "replacedOrderInGroup": 3,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-3-{ts}.png",
  "totalSlides": 10,
  "slides": [ /* ... full ordered list ... */ ],
  "mediaUrls": [ /* ... full ordered list ... */ ],
  "message": "Slide 4 replaced. The other slides are unchanged. If you already attached the carousel to a draft post, refresh the attachments — the old slide URL is now soft-deleted."
}

POSTZEE_APPEND_CAROUSEL_SLIDE

Append ONE new slide to the end of an existing carousel. Use for iterative authoring — when the user wants to build the carousel slide-by-slide (“show me slide 1… ok now slide 2…”), this keeps every new slide landing in the SAME MediaGroup instead of producing N orphan single-slide groups in the gallery. Parameters:

Parameter	Type	Required	Description
`mediaGroupId`	string	Yes	The id of the carousel you’re growing. Returned by `POSTZEE_RENDER_CAROUSEL` (first slide) or a previous `APPEND_CAROUSEL_SLIDE` call.
`slide`	object	Yes	`{ html, width?, height? }` — same shape as one entry of `RENDER_CAROUSEL.slides`.

The new slide is appended at the next available orderInGroup (gap-safe — if intermediate slides were deleted, this picks max(orderInGroup) + 1, never reuses a free slot). Cover thumbnail is unchanged. Iterative authoring pattern. First slide should still go through POSTZEE_RENDER_CAROUSEL (it’s what creates the MediaGroup). Every subsequent slide goes through APPEND_CAROUSEL_SLIDE with the same mediaGroupId. Calling RENDER_CAROUSEL a second time for the same logical carousel produces a new group and breaks the iterative flow — don’t. Returns:

{
  "success": true,
  "mediaGroupId": "uuid",
  "appendedOrderInGroup": 7,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-7-{ts}.png",
  "totalSlides": 8,
  "slides": [ /* ... full ordered list including the new one ... */ ],
  "mediaUrls": [ /* ... full ordered list ... */ ]
}

There is no insert-in-the-middle, reorder, or delete primitive in v1. APPEND_CAROUSEL_SLIDE only adds to the END. If the user asks to insert at a specific position, swap two slides, or remove one, fall back to POSTZEE_RENDER_CAROUSEL with a fresh script.

HeyGen

HeyGen tools require a HeyGen API key configured in your Postzee account. Connect at Settings → HeyGen integration. HeyGen video generation bills on your HeyGen account, not Postzee credits.

POSTZEE_LIST_HEYGEN_AVATARS

List available HeyGen avatars (filter by gender, age, style, etc. on the client side). Parameters: None Returns: Array of avatars from your HeyGen account.

POSTZEE_LIST_HEYGEN_VOICES

List available HeyGen voices. Parameters: None Returns: Array of voices from your HeyGen account, with language and gender info.

POSTZEE_GENERATE_HEYGEN_VIDEO

Create an avatar video with HeyGen. Async operation — poll with POSTZEE_CHECK_JOB. Parameters:

Parameter	Type	Required	Description
`script`	string	Yes	Text for the avatar to speak (20-1500 chars)
`avatarId`	string	Yes	From `POSTZEE_LIST_HEYGEN_AVATARS`
`voiceId`	string	Yes	From `POSTZEE_LIST_HEYGEN_VOICES`
`aspectRatio`	string	No	`"16:9"` or `"9:16"`. Default: `"16:9"`

Returns: same shape as POSTZEE_GENERATE_IMAGE — jobId + status: "processing". The response also notes that HeyGen credits (not Postzee) will be consumed.

Posting

POSTZEE_CREATE_POST

Create, schedule, or publish a post to a social media channel. Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`"now"` (publish immediately), `"draft"`, or `"schedule"`
`date`	string	Schedule only	UTC datetime (e.g. `"2026-04-24T15:00:00Z"`) — required when `type` is `"schedule"`
`channelId`	string	Yes	Channel id from `POSTZEE_LIST_CHANNELS`
`text`	string	Yes	Post text content
`mediaUrls`	string[]	No	Media URLs (in display order — array order = slide order for carousels)
`settings`	object	No	Per-platform publish settings. Send a flat object with only the fields relevant to the target channel’s network — e.g. `{ "post_type": "story" }` for Instagram, `{ "privacy_level": "PUBLIC_TO_EVERYONE", "duet": true }` for TikTok. The MCP routes settings to the right validator based on the channel. See channel platform settings for the full reference.

Returns (success):

{ "success": true, "postId": "post-uuid", "message": "Post queued for immediate publishing successfully. Poll POSTZEE_GET_POST with this postId until state is \"PUBLISHED\"..." }

Publishing is asynchronous: POSTZEE_CREATE_POST returns a postId immediately, but the post is not live yet. Poll POSTZEE_GET_POST with that postId until state is "PUBLISHED" to obtain the platform post id (releaseId) and permalink (releaseURL). Returns (failure):

{ "success": false, "error": "<error_code>", "message": "...", "upgradeUrl": "https://dashboard.postzee.app/billing" }

Possible error codes:

Code	Meaning
`subscription_required`	The current plan doesn’t allow publishing or the monthly post cap was reached. `upgradeUrl` is included.
`date_required`	`type: "schedule"` was sent without a `date`.
`invalid_date`	The `date` string is not a valid UTC ISO timestamp.
`organization_not_found`	The MCP key resolved to an organization that doesn’t exist (rare).
`post_failed`	Provider/network error during publish. Retry once; if it persists, surface the `message`.

POSTZEE_GET_POST

Get a single post’s publication status — poll this after POSTZEE_CREATE_POST to obtain the platform post id and permalink once the post goes live. Parameters:

Parameter	Type	Required	Description
`postId`	string	Yes	The post id returned by `POSTZEE_CREATE_POST`

Returns (success):

{
  "success": true,
  "id": "post-uuid",
  "state": "PUBLISHED",
  "published": true,
  "releaseId": "17895695668004550",
  "releaseURL": "https://www.instagram.com/p/Cabc123/",
  "platform": "instagram",
  "channelId": "channel-uuid",
  "channelName": "My Instagram",
  "publishDate": "2026-04-29T15:00:00Z",
  "message": "Post is published. releaseId is the native platform post id; releaseURL is the public permalink."
}

Field	Description
`state`	`QUEUE` (waiting), `PUBLISHED`, `ERROR`, or `DRAFT`
`published`	`true` when `state` is `PUBLISHED`
`releaseId`	The native platform post id (e.g. the Instagram media id). `null` until published
`releaseURL`	The public permalink to the post. `null` until published

While the post is still publishing, state is "QUEUE" and releaseId/releaseURL are null — keep polling until state is "PUBLISHED" (or "ERROR" if publishing failed). Returns (failure):

{ "success": false, "error": "post_not_found", "message": "Post <id> not found for this organization." }

Legacy tools (deprecated)

The following tools still work but are superseded:

POSTZEE_LIST_IMAGE_MODELS → use POSTZEE_LIST_MODELS_DETAILED({ type: "image" })
POSTZEE_LIST_VIDEO_MODELS → use POSTZEE_LIST_MODELS_DETAILED({ type: "video" })

They will be kept for at least 90 days for backwards compatibility, then removed in a future major version.

Async workflow pattern

Image, video, and HeyGen generation are async. The recommended workflow:

Validate first — POSTZEE_VALIDATE_GENERATION to catch param errors and insufficient-credit cases without burning credits
Estimate cost — POSTZEE_ESTIMATE_GENERATION_COST if you need the precise number to show the user
Enhance the prompt — POSTZEE_ENHANCE_PROMPT (free)
Generate — POSTZEE_GENERATE_IMAGE / POSTZEE_GENERATE_VIDEO / POSTZEE_GENERATE_HEYGEN_VIDEO → returns jobId
Poll — POSTZEE_CHECK_JOB every few seconds. Typical latencies: 10-60s for images, 30-180s for videos, up to 5 min for HeyGen
On success — use mediaUrl in POSTZEE_CREATE_POST

Standard error format

All write/generate tools return:

{
  "success": true | false,
  "error": "<machine_code>",  // only on failure
  "message": "<human readable>",
  "...": "tool-specific fields on success"
}

Branch on the error machine code for logic; use message to narrate to the user (translated to their language).

Rate limits

Endpoint	Limit
HTTP POST	60 requests/minute
SSE connection (legacy)	30 requests/minute
AI generation (`GENERATE_*`)	10 requests/minute

Claude Code

Connect Postzee to Claude Code.

OpenClaw

Connect Postzee to OpenClaw.

Hermes Agent

Connect Postzee to Hermes Agent.

MCP Overview

Back to MCP overview.

​Quick reference

​Context & Discovery

​POSTZEE_GET_CONTEXT

​POSTZEE_LIST_PLANS

​POSTZEE_LIST_CREDIT_PACKAGES

​Models & Specs

​POSTZEE_LIST_MODELS_DETAILED

​POSTZEE_LIST_PLATFORM_SPECS

​POSTZEE_GET_BEST_POSTING_TIMES

​Cost & Validation

​POSTZEE_ESTIMATE_GENERATION_COST

​POSTZEE_VALIDATE_GENERATION

​Channels & Credits

​POSTZEE_LIST_CHANNELS

​POSTZEE_GET_CREDITS

​Media Memory

​POSTZEE_LIST_MEDIA

​POSTZEE_UPLOAD_MEDIA

​Prompt Enhancement

​POSTZEE_ENHANCE_PROMPT

​Generation

​POSTZEE_GENERATE_IMAGE

​POSTZEE_GENERATE_VIDEO

​POSTZEE_CHECK_JOB

​Images & Carousels

​POSTZEE_RENDER_IMAGE

​POSTZEE_RENDER_CAROUSEL

​POSTZEE_REPLACE_CAROUSEL_SLIDE

​POSTZEE_APPEND_CAROUSEL_SLIDE

​HeyGen

​POSTZEE_LIST_HEYGEN_AVATARS

​POSTZEE_LIST_HEYGEN_VOICES

​POSTZEE_GENERATE_HEYGEN_VIDEO

​Posting

​POSTZEE_CREATE_POST

​POSTZEE_GET_POST

​Legacy tools (deprecated)

​Async workflow pattern

​Standard error format

​Rate limits

Claude Code

OpenClaw

Hermes Agent

MCP Overview

Quick reference

Context & Discovery

POSTZEE_GET_CONTEXT

POSTZEE_LIST_PLANS

POSTZEE_LIST_CREDIT_PACKAGES

Models & Specs

POSTZEE_LIST_MODELS_DETAILED

POSTZEE_LIST_PLATFORM_SPECS

POSTZEE_GET_BEST_POSTING_TIMES

Cost & Validation

POSTZEE_ESTIMATE_GENERATION_COST

POSTZEE_VALIDATE_GENERATION

Channels & Credits

POSTZEE_LIST_CHANNELS

POSTZEE_GET_CREDITS

Media Memory

POSTZEE_LIST_MEDIA

POSTZEE_UPLOAD_MEDIA

Prompt Enhancement

POSTZEE_ENHANCE_PROMPT

Generation

POSTZEE_GENERATE_IMAGE

POSTZEE_GENERATE_VIDEO

POSTZEE_CHECK_JOB

Images & Carousels

POSTZEE_RENDER_IMAGE

POSTZEE_RENDER_CAROUSEL

POSTZEE_REPLACE_CAROUSEL_SLIDE

POSTZEE_APPEND_CAROUSEL_SLIDE

HeyGen

POSTZEE_LIST_HEYGEN_AVATARS

POSTZEE_LIST_HEYGEN_VOICES

POSTZEE_GENERATE_HEYGEN_VIDEO

Posting

POSTZEE_CREATE_POST

POSTZEE_GET_POST

Legacy tools (deprecated)

Async workflow pattern

Standard error format

Rate limits