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_caption_render`	`videos:read`	Poll a video caption render until the new MP4 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_captions`	`videos:generate`	Burn timed captions onto an existing video
`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

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: powerpost_create_post (from 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.
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, and scale animations.
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_caption_render`	`videos:read`	Poll a video caption render until the new MP4 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_captions`	`videos:generate`	Burn timed captions onto an existing video
`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

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: powerpost_create_post (from 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.
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, and scale animations.
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)

Typical flow

Notes

On this page

MCP Server

Endpoint

Connecting a client

Connecting with OAuth instead

Choosing a workspace

Tools

Info (read)

Action (write)

Typical flow

Notes

On this page