MCP Server

PowerPost runs a remote MCP server, so AI assistants like Claude and Cursor can generate captions and images, create posts, publish, and read analytics on your behalf. Every MCP tool maps to an endpoint in the v1 API and respects the same API key, scopes, and rate limits.

Endpoint

https://powerpost.ai/api/mcp

Transport is Streamable HTTP. Authenticate with a PowerPost API key as a bearer token, the same key you use for the REST API.

Connecting a client

Most clients let you add a remote MCP server by URL with custom headers. Add this to your client's MCP config (for example .mcp.json in Claude Code or Cursor):

{
  "mcpServers": {
    "powerpost": {
      "url": "https://powerpost.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer pp_live_sk_YOUR_KEY_HERE",
        "X-Workspace-Id": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

Create a key in Settings → API. The key's scopes decide which tools work, so grant the scopes you need (or "Full access").

Connecting with OAuth instead

Clients that support the MCP "Connect" flow (Claude.ai, Claude Code, and others) can skip the manual key: point them at https://powerpost.ai/api/mcp with no credentials, and the client discovers this server's OAuth endpoints on its own, redirects you to log in and approve access, then starts using the connection — no copying and pasting a key.

OAuth connections always get full API access (same as a "Full access" key). To limit what the assistant can do, disable tools in the client (e.g. Claude's tool permissions). Connections show up in Settings → API.

Choosing a workspace

Most tools act inside a workspace. You can either:

Set X-Workspace-Id once as a connection header (recommended), or
Pass workspace_id as an argument on each call.

Run powerpost_list_workspaces to find your workspace IDs.

Tools

Every public v1 endpoint is a tool here, plus powerpost_list_workspaces so you can find workspace IDs. Tools are split into info (lookups) and action (create, change, publish, or delete). Some clients warn before running tools that post publicly or delete data.

Info (read)

Tool	Scope	What it does
`powerpost_list_workspaces`	—	List workspaces this key can use
`powerpost_get_credits`	`account:read`	Current credit balance
`powerpost_list_content_generations`	`content:read`	List content generations
`powerpost_get_content_generation`	`content:read`	Get one content generation + outputs
`powerpost_get_image_generation`	`images:read`	Get one image generation
`powerpost_get_video_generation`	`videos:read`	Get one video generation
`powerpost_get_video_stitch_render`	`videos:read`	Poll a stitch render and get the combined video media ID
`powerpost_get_video_audio_render`	`videos:read`	Poll an audio render and get the new video media ID
`powerpost_get_video_caption_render`	`videos:read`	Poll a video caption render until the new MP4 is ready
`powerpost_list_audio_voices`	`audio:read`	List voices you can pass as `voice_id` for speech
`powerpost_get_audio_generation`	`audio:read`	Poll an audio generation until the MP3 is ready
`powerpost_get_post`	`posts:read`	Get a post and its items
`powerpost_list_post_items`	`posts:read`	List published posts (platform, date range, limit)
`powerpost_get_post_item_analytics`	`analytics:read`	Engagement analytics for an item
`powerpost_list_calendar_entries`	`calendar:read`	List calendar entries in a date range
`powerpost_get_calendar_entry`	`calendar:read`	Get a calendar entry

Action (write)

Tool	Scope	What it does
`powerpost_generate_content`	`content:generate`	Start a caption generation from a prompt, media, or both
`powerpost_regenerate_content`	`content:generate`	Regenerate one platform with optional feedback
`powerpost_generate_image`	`images:generate`	Start an image generation
`powerpost_generate_video`	`videos:generate`	Start a video generation
`powerpost_upload_media`	`media:write`	Upload media (base64 → same as REST upload)
`powerpost_render_video_stitch`	`videos:generate`	Stitch ordered videos with matching aspect ratios and optional transitions
`powerpost_render_video_audio`	`videos:generate`	Mix workspace audio into a video with independent volumes and start times
`powerpost_render_video_captions`	`videos:generate`	Burn timed captions onto an existing video
`powerpost_generate_audio`	`audio:generate`	Generate speech, sound effects, ambience, or music
`powerpost_create_post`	`posts:write`	Create a draft post
`powerpost_publish_post`	`posts:publish`	Publish a post now (goes live)
`powerpost_schedule_post`	`posts:publish`	Schedule a post
`powerpost_cancel_publish`	`posts:publish`	Cancel a publish/schedule
`powerpost_retry_post_item`	`posts:publish`	Retry a failed item
`powerpost_create_calendar_entry`	`calendar:write`	Create a calendar entry
`powerpost_update_calendar_entry`	`calendar:write`	Update a calendar entry
`powerpost_delete_calendar_entry`	`calendar:write`	Delete a calendar entry

Which caption tool should I use?

Goal	Start tool	Status tool
Write social post text from a prompt or media	`powerpost_generate_content`	`powerpost_get_content_generation`
Burn supplied text and timings into a video	`powerpost_render_video_captions`	`powerpost_get_video_caption_render`

Video caption rendering does not transcribe audio or detect word timings. Supply a workspace video media_id and 1–500 timed cues. Times are seconds from the beginning of the video, including word highlight windows; animation durations are milliseconds. Omitted styling uses uppercase Montserrat Black text with fades.

The render tool returns caption_render_id. Pass that value as id to the status tool, using the same workspace. Poll until completed or failed; on success, video.media_id identifies the new captioned MP4. Each new render costs credits, so poll the existing job instead of starting it again.

See Video captions for exact MCP arguments, copyable examples, all defaults, styling rules, and output limitations.

Typical flow

Info: powerpost_list_workspaces (and optionally powerpost_get_credits)
Action: generate content / image / video → info: poll the matching get_*_generation until completed or failed
Action (optional): powerpost_regenerate_content to rewrite one platform with feedback (returns new content immediately)
Action (optional): powerpost_render_video_captions on an uploaded or generated video → info: poll powerpost_get_video_caption_render until completed or failed, then use video.media_id
Action (optional): for speech, call powerpost_list_audio_voices and pass an id as voice_id. Then powerpost_generate_audio → info: poll powerpost_get_audio_generation until completed or failed. Use audio.url to download the MP3, or keep audio_generation_id / audio.media_id and fetch again for a fresh URL. To use it in a post, call powerpost_render_video_audio with the video ID and audio.media_id, then poll powerpost_get_video_audio_render and pass the resulting video.media_id to powerpost_create_post. Raw audio IDs cannot be attached directly.
Action: powerpost_create_post (from caption/image/video generation IDs or raw content)
Action: powerpost_publish_post or powerpost_schedule_post
Info: powerpost_get_post / powerpost_get_post_item_analytics after it goes live

Notes

Generation is async. The generate tools return an ID right away; poll the matching get_*_generation tool until the status is completed or failed. Video caption renders work the same way: start with powerpost_render_video_captions, then poll powerpost_get_video_caption_render.
Audio generation is its own job. For speech, call powerpost_list_audio_voices first and pass an id as voice_id. powerpost_generate_audio returns audio_generation_id; poll powerpost_get_audio_generation. Do not send a provider. Mode-specific settings live under provider_options. Completed audio is stored in the media library as media_type: audio and cannot be attached directly to posts. Mix it into a video using Video audio, then publish the resulting MP4.
Caption tools match the REST API. powerpost_generate_content accepts the same body as Generate content (prompt and/or media_ids, plus optional source_urls). powerpost_render_video_captions accepts the same body as Video captions, including defaults, per-cue style, spans, scale animations, and spoken-word highlight windows.
Uploads have no file picker. powerpost_upload_media takes base64 data plus mime_type, then posts to the same /api/v1/media/upload endpoint as the REST API. It does not download files from URLs.
Post type limits match the REST API. Media min/max, captions, and titles follow the post type limits (e.g. tiktok-photos allows 1–35 images). Create, publish, and schedule use the same validation.
Errors come straight from the API. A missing scope, bad input, or insufficient credits returns the same message you'd get from the REST endpoint.
Scopes gate tools. A key without posts:publish can still list and draft; publish tools will fail with a clear missing-scope message.

Endpoint

https://powerpost.ai/api/mcp

Transport is Streamable HTTP. Authenticate with a PowerPost API key as a bearer token, the same key you use for the REST API.

Connecting a client

Most clients let you add a remote MCP server by URL with custom headers. Add this to your client's MCP config (for example .mcp.json in Claude Code or Cursor):

{
  "mcpServers": {
    "powerpost": {
      "url": "https://powerpost.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer pp_live_sk_YOUR_KEY_HERE",
        "X-Workspace-Id": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

Create a key in Settings → API. The key's scopes decide which tools work, so grant the scopes you need (or "Full access").

Connecting with OAuth instead

Choosing a workspace

Most tools act inside a workspace. You can either:

Set X-Workspace-Id once as a connection header (recommended), or
Pass workspace_id as an argument on each call.

Run powerpost_list_workspaces to find your workspace IDs.

Tools

Info (read)

Tool	Scope	What it does
`powerpost_list_workspaces`	—	List workspaces this key can use
`powerpost_get_credits`	`account:read`	Current credit balance
`powerpost_list_content_generations`	`content:read`	List content generations
`powerpost_get_content_generation`	`content:read`	Get one content generation + outputs
`powerpost_get_image_generation`	`images:read`	Get one image generation
`powerpost_get_video_generation`	`videos:read`	Get one video generation
`powerpost_get_video_stitch_render`	`videos:read`	Poll a stitch render and get the combined video media ID
`powerpost_get_video_audio_render`	`videos:read`	Poll an audio render and get the new video media ID
`powerpost_get_video_caption_render`	`videos:read`	Poll a video caption render until the new MP4 is ready
`powerpost_list_audio_voices`	`audio:read`	List voices you can pass as `voice_id` for speech
`powerpost_get_audio_generation`	`audio:read`	Poll an audio generation until the MP3 is ready
`powerpost_get_post`	`posts:read`	Get a post and its items
`powerpost_list_post_items`	`posts:read`	List published posts (platform, date range, limit)
`powerpost_get_post_item_analytics`	`analytics:read`	Engagement analytics for an item
`powerpost_list_calendar_entries`	`calendar:read`	List calendar entries in a date range
`powerpost_get_calendar_entry`	`calendar:read`	Get a calendar entry

Action (write)

Tool	Scope	What it does
`powerpost_generate_content`	`content:generate`	Start a caption generation from a prompt, media, or both
`powerpost_regenerate_content`	`content:generate`	Regenerate one platform with optional feedback
`powerpost_generate_image`	`images:generate`	Start an image generation
`powerpost_generate_video`	`videos:generate`	Start a video generation
`powerpost_upload_media`	`media:write`	Upload media (base64 → same as REST upload)
`powerpost_render_video_stitch`	`videos:generate`	Stitch ordered videos with matching aspect ratios and optional transitions
`powerpost_render_video_audio`	`videos:generate`	Mix workspace audio into a video with independent volumes and start times
`powerpost_render_video_captions`	`videos:generate`	Burn timed captions onto an existing video
`powerpost_generate_audio`	`audio:generate`	Generate speech, sound effects, ambience, or music
`powerpost_create_post`	`posts:write`	Create a draft post
`powerpost_publish_post`	`posts:publish`	Publish a post now (goes live)
`powerpost_schedule_post`	`posts:publish`	Schedule a post
`powerpost_cancel_publish`	`posts:publish`	Cancel a publish/schedule
`powerpost_retry_post_item`	`posts:publish`	Retry a failed item
`powerpost_create_calendar_entry`	`calendar:write`	Create a calendar entry
`powerpost_update_calendar_entry`	`calendar:write`	Update a calendar entry
`powerpost_delete_calendar_entry`	`calendar:write`	Delete a calendar entry

Which caption tool should I use?

Goal	Start tool	Status tool
Write social post text from a prompt or media	`powerpost_generate_content`	`powerpost_get_content_generation`
Burn supplied text and timings into a video	`powerpost_render_video_captions`	`powerpost_get_video_caption_render`

See Video captions for exact MCP arguments, copyable examples, all defaults, styling rules, and output limitations.

Typical flow

Info: powerpost_list_workspaces (and optionally powerpost_get_credits)
Action: generate content / image / video → info: poll the matching get_*_generation until completed or failed
Action (optional): powerpost_regenerate_content to rewrite one platform with feedback (returns new content immediately)
Action (optional): powerpost_render_video_captions on an uploaded or generated video → info: poll powerpost_get_video_caption_render until completed or failed, then use video.media_id
Action (optional): for speech, call powerpost_list_audio_voices and pass an id as voice_id. Then powerpost_generate_audio → info: poll powerpost_get_audio_generation until completed or failed. Use audio.url to download the MP3, or keep audio_generation_id / audio.media_id and fetch again for a fresh URL. To use it in a post, call powerpost_render_video_audio with the video ID and audio.media_id, then poll powerpost_get_video_audio_render and pass the resulting video.media_id to powerpost_create_post. Raw audio IDs cannot be attached directly.
Action: powerpost_create_post (from caption/image/video generation IDs or raw content)
Action: powerpost_publish_post or powerpost_schedule_post
Info: powerpost_get_post / powerpost_get_post_item_analytics after it goes live

Notes

Generation is async. The generate tools return an ID right away; poll the matching get_*_generation tool until the status is completed or failed. Video caption renders work the same way: start with powerpost_render_video_captions, then poll powerpost_get_video_caption_render.
Audio generation is its own job. For speech, call powerpost_list_audio_voices first and pass an id as voice_id. powerpost_generate_audio returns audio_generation_id; poll powerpost_get_audio_generation. Do not send a provider. Mode-specific settings live under provider_options. Completed audio is stored in the media library as media_type: audio and cannot be attached directly to posts. Mix it into a video using Video audio, then publish the resulting MP4.
Caption tools match the REST API. powerpost_generate_content accepts the same body as Generate content (prompt and/or media_ids, plus optional source_urls). powerpost_render_video_captions accepts the same body as Video captions, including defaults, per-cue style, spans, scale animations, and spoken-word highlight windows.
Uploads have no file picker. powerpost_upload_media takes base64 data plus mime_type, then posts to the same /api/v1/media/upload endpoint as the REST API. It does not download files from URLs.
Post type limits match the REST API. Media min/max, captions, and titles follow the post type limits (e.g. tiktok-photos allows 1–35 images). Create, publish, and schedule use the same validation.
Errors come straight from the API. A missing scope, bad input, or insufficient credits returns the same message you'd get from the REST endpoint.
Scopes gate tools. A key without posts:publish can still list and draft; publish tools will fail with a clear missing-scope message.

MCP Server

Endpoint

Connecting a client

Connecting with OAuth instead

Choosing a workspace

Tools

Info (read)

Action (write)

Which caption tool should I use?

Typical flow

Notes

On this page

MCP Server

Endpoint

Connecting a client

Connecting with OAuth instead

Choosing a workspace

Tools

Info (read)

Action (write)

Which caption tool should I use?

Typical flow

Notes

On this page