postnext

Add one block to a bio page. Types: link, featured, header, email, latestposts, embed, text, image, gallery, faq, divider, product, event, presave, episode, booking, hours, collection. Required fields per type — link/featured: url; product: title+url; event: title+startDate; presave: title+releaseDate+links; episode: mode plus title+url (manual) or feedUrl (rss); booking: provider+url; hours: timezone+days; header: text; text: richText; image: imageUrl; gallery: images; faq: faqItems; embed: embedUrl from a supported provider; email/latestposts/divider: none. All URLs must be http(s). The response returns the block AS STORED, so any field the server rejected is visibly absent. Calling twice with the same type+url returns the existing block instead of duplicating it. The phase field stages a block around a release date: 'before' shows it only until the drop, 'after' only from the drop onwards, and 'always' clears the staging so it shows either way. Phase has NO effect until a campaign is set in the dashboard — check get_mini_site.campaign first and tell the user if it is null.

Cancel a scheduled post and remove it from the publish queue. The draft is preserved (not deleted). Idempotent — safe to call on already-cancelled posts.

Generate a one-time authorization URL for connecting a social channel. The user must open the URL in a browser and authorize.

Create a blog content plan (the "Post Planner") for a brand profile. Topics are generated asynchronously, so the plan returns immediately in status "generating" (poll list_blog_plans for progress). Paid feature (Basic+); Business/Teams plans also auto-generate and publish posts to a connected WordPress blog. Pass brandProfileId to choose the brand (defaults to the team's active profile) and integrationId to publish to a specific blog (defaults to the single connected one). NOTE: on Business/Teams with a connected blog, generated posts AUTO-PUBLISH to WordPress by default; pass autoPublish:false to keep them as drafts.

Create a new draft post for a platform. Drafts are not auto-published. For an X or Threads thread, pass threadParts (one string per post, 2 to 25) instead of content; each post must fit the platform limit (X 280, or 25,000 for a paid X account; Threads 500). When the user has multiple connected channels for the same platform (e.g. three Twitter accounts), pass channelName (e.g. "@acme") to target a specific one — call list_connected_accounts first to see the available handles. You can also pass the account providerId (with or instead of channelName): it still identifies the account after its handle changes. Pass clientRequestId for idempotent retries within 5 minutes. For an Instagram draft with exactly one video in mediaUrls, pass instagramTrialReel ("auto" or "manual") to publish it as a trial reel shown to non-followers first; "auto" lets Instagram share it with followers if it performs well; the video URL must end in .mp4, .mov or .avi with no query string, which is how PostNext recognises a video. To give images alt text (an image description for screen readers), pass media instead of mediaUrls: [{ "url": "...", "alt": "..." }] with an optional type (IMAGE, VIDEO or GIF; detected from the URL when missing). Alt text limits: X and Instagram 1,000 characters, Bluesky 2,000, LinkedIn 300 (saved for LinkedIn but not sent to it yet). Alt text is ignored on video and GIF. Returns dashboardUrl — a clickable link to view/edit the draft in the PostNext dashboard.

Permanently delete a draft post. Refuses to delete posts that are scheduled or published — use cancel_scheduled_post for those.

Get an account-health summary across all connected social accounts: connected-account count, scheduled/published/failed post counts, draft count, and tokens expiring in the next 7 days. Optionally filter by platform. Requires a paid plan.

Recommend the best (dayOfWeek, hour) slots for the user's next post on a given platform, ranked by engagement-per-post over the past 90 days. Twitter and Instagram return engagement-weighted scores; LinkedIn / Threads / TikTok rank by post frequency only (engagement collection deferred). Times are in the supplied IANA timezone (defaults to UTC). Paid plan required.

Aggregate performance for one connected channel, or for every channel at once. Returns impressions, reach, likes, comments and engagement rate for the period, the change against the preceding period of the same length, and the follower series. Omit platform for a team-wide total; pass platform (plus channelName or providerId from list_connected_accounts when that platform has more than one account connected) to scope it. providerId still identifies the account after its handle changes. period is 7d, 30d, 90d or all, defaulting to 30d. Use this for "how did LinkedIn do this month?"; use get_post_metrics for a single post and get_best_time_to_post for scheduling.

Check whether the team is connected to a WordPress blog and get a snippet of the most recent blog post. Returns blogConnected (an active WordPress integration exists), the integration summary (no secrets), and the latest post's title + snippet + publish status/URL. Read-only, no credit cost. Use before create_blog_plan or test_blog_connection to see if a blog is wired up and what was last published.

Read one bio page in full: profile header, social icons, every content block (links, products, events, opening hours, podcast episodes, pre-saves and more), SEO metadata, theme and auto-pin settings. Omit siteId when the team has exactly one site. Long text blocks are truncated to a 300-character preview. Never returns email-sync credentials or tracking pixel IDs. suspended: true means PostNext took the page offline; it cannot be published again until support reviews it (support@postnext.io).

Performance of a bio page: LIFETIME totals for views, clicks, best-performing links, visitor source/device/country and AI-crawler reads, plus which published posts drove clicks (post-to-click attribution) over a configurable recent window. Every figure except the attribution rows is an all-time counter, not a windowed one — say so when reporting numbers. Omit siteId when the team has exactly one site.

Return the user's plan + billing-date info: tier, renewal date, trial end date, and cancel-at-period-end state. Call when the user asks "when does my plan renew?", "how many days left on my trial?", or "is my subscription cancelling?". For quotas and usage (channels, AI credits, posts), call get_plan_limits instead — this tool is purely about plan identity and billing dates.

Return the user's current subscription tier and per-tier quotas (channels, storage, AI credits, posting). Available on every plan (no AI credit cost). Call this when the user asks "what plan am I on?" or "what are my limits?", or proactively before suggesting an action that might be blocked (e.g. before create_post_draft when aiCalls is low, before schedule_post when posts.current is close to posts.limit, or before connect_channel when channel slots are near the cap).

Fetch a single post (draft or scheduled) by its postId. Returns the full provider-by-platform content map plus status, timestamps, and dashboardUrl — a clickable link to view the post in the PostNext dashboard.

Fetch engagement metrics (likes, comments, shares, impressions) for a published post across every platform it was sent to. Twitter and Instagram return populated metrics; LinkedIn/Threads/TikTok return publish status + URL only (engagement not collected for those platforms yet).

Diagnose what happened to a scheduled post: queue/publish state, per-platform success or error, and the worker's processing time. Useful when a user asks "did my post go out?" or "why did Tuesday's post fail on LinkedIn?". Returns isScheduled=false for posts that exist as drafts but were never moved into the publish queue.

Save images or videos the user attached to their message into their PostNext asset library. Returns each saved file's url: pass it in mediaUrls (or media) of create_post_draft or update_post_draft. Files that could not be imported are listed in failed with the reason; the saved ones need no retry. Use this when the user has attached a photo or video and wants it in a post. JPEG, PNG, GIF, WebP or AVIF images and MP4, MOV, WebM or AVI videos, up to 50MB each, at most 10 per call; uses the account's storage.

List the team's blog plans (the "Post Planner"), newest first, with status, per-status topic counts, credit-reservation info, and a dashboard link. Read-only, no credit cost. Optionally filter by status (generating/active/paused/completed/cancelled/failed). Use to see what blog plans exist before creating a new one or to check a plan's generation progress.

List the social accounts connected to the user's team. Each account has its handle and its providerId; the providerId stays the same when the handle changes, so pass it (with or instead of channelName) to create_post_draft and get_channel_analytics.

List the user's draft posts (not yet scheduled). Each entry includes platforms[] (deduplicated platform labels), channelNames[] (the per-provider account handles), a content preview from the first provider, and dashboardUrl — a clickable link to view/edit the draft in the PostNext dashboard. Use the platforms + channelNames fields to filter the list client-side when the caller wants drafts for a specific platform or account.

List the bio pages (mini sites) belonging to the currently selected team, with their public URL, publish state and setup progress. Use this first when the user mentions "my bio page", "link in bio" or "mini site" — every other mini-site tool takes the siteId this returns (and can omit it entirely when the team has exactly one site). suspended: true means PostNext took that page offline; it cannot be published again until support reviews it (support@postnext.io).

List scheduled (queued for publish, not yet sent) posts. Joins each ScheduledPost with its PostGroup to include content preview + the channelName (handle) so the caller can filter by handle client-side. Returns up to limit posts ordered by scheduledAt ascending.

List the teams the authenticated user belongs to (as owner or admin), with the currently active team marked. Use set_current_team to switch.

Remove one block from a bio page by its blockId (for example a finished tour date or a retired product link). Call get_mini_site first to find the id. This changes a publicly visible page immediately.

Recommended upload tool for images and videos of any size. TWO STEPS only: (1) call this tool with {filename, contentType, sizeBytes} → get back {uploadId, uploadUrl, uploadToken, instructions}. (2) From your bash sandbox, PUT the file bytes to uploadUrl with the Bearer token — the curl command is in instructions. The PUT response is JSON containing the final asset URL you should pass to create_post_draft.mediaUrls or update_post_draft.mediaUrls. No follow-up MCP call is required — the PUT handler creates the Asset doc, validates magic bytes, and returns everything inline. Use this, not the inline upload_asset tool, for anything larger than ~8KB — bytes-through-tool-args truncates. Pre-charges your storage quota by sizeBytes to defeat the concurrent-request TOCTOU race; refunded automatically if you never PUT within 10 min, or if the actual upload size is smaller than declared, or if the PUT fails magic-byte validation. Allowed types: JPEG, PNG, WebP, GIF, MP4, WebM. Per-request hard cap: 50MB on top of your plan's storage limit.

IF YOUR SANDBOX CAN'T REACH mcp.postnext.io (e.g. you receive x-deny-reason: host_not_allowed from your bash curl), DO NOT KEEP RETRYING — the host isn't addressable from your environment. Tell the user to upload the image manually at https://app.postnext.io/my-assets, then ask them to paste back the asset URL so you can use it in create_post_draft.mediaUrls. This is the documented fallback for environments with restricted egress (most notably the Claude.ai chat sandbox, whose allowlist is fixed). Also: do not call this tool again expecting a different uploadUrl — every uploadUrl points at the same host.

Move a draft post into the publish queue at a future time. The draft must already exist (use create_post_draft first). Optional platform and channelName narrow which providers in a multi-channel cross-post get scheduled — e.g. queue only the @acme X variant without scheduling the IG / Threads / other-X-account copies. When both are omitted, all providers in the PostGroup are queued.

Text-search across the user's posts (drafts, scheduled, published). Case-insensitive substring match on post content. Optionally filter by status or platform.

Search and filter the available MCP tool catalog by free-text query, category, or intent. Useful when you have many tools available and want to narrow to the ones relevant to the user's current task without scanning every description. Returns categories, requiresScope, one-line descriptions, and the use-case tags that matched. Free for all plans (discovery surface).

Switch the active team for this Bearer token. The user must be a member of the target team. Takes effect immediately for subsequent tool calls in this session, and persists across sessions when authenticated via OAuth (not API key).

Test connectivity to the team's connected WordPress blog (the PostNext plugin) and update the integration's health status. Returns whether the plugin is reachable + the token valid, plus the plugin version and capabilities. Pass integrationId when more than one blog is connected; otherwise the single connected blog is used. Business/Teams feature (a blog must be connected first).

Patch the user's active brand profile — voice, themes, expertise areas, personality traits, hashtag set, audience-size estimates, or bio. Useful when the user wants Claude to refine their brand voice based on a transcript, style guide, or competitor analysis without leaving the conversation. Only the active profile is mutated; profile selection / creation must happen in the web app.

Patch one existing block on a bio page — change a link title or URL, a product price, an event date, opening hours, or the display order. Only the fields you pass are changed; everything else is left alone. The block type cannot be changed (remove it and add a new one instead). The response returns the block AS STORED, so any value the server rejected is visibly absent: updated lists only the fields that actually changed, and any requested field the server did not keep comes back under ignored — check it before telling the user a change was applied. To un-stage a block from a release rollout, pass phase:"always" — that clears the staging (there is no other way to remove it). Use get_mini_site first to get the blockId.

Update an existing draft post. At least one of content, threadParts, mediaUrls or media is required. To give images alt text (an image description for screen readers), pass media instead of mediaUrls: [{ "url": "...", "alt": "..." }] with an optional type (IMAGE, VIDEO or GIF); it replaces the media on the draft. Alt text limits: X and Instagram 1,000 characters, Bluesky 2,000, LinkedIn 300 (saved for LinkedIn but not sent to it yet); it is ignored on video and GIF. For a thread draft (X/Threads), pass threadParts (one string per post) to replace its posts; content only edits a single-post draft. Optional platform scopes the update to one platform on a multi-platform cross-post (e.g. rewrite just the Twitter copy without overwriting the Instagram caption). When the user has multiple channels per platform (e.g. three Twitter accounts), additionally pass channelName (e.g. "@acme") to narrow the update to one specific account's copy. When both are omitted, all providers in the draft are overwritten uniformly. Returns dashboardUrl — a clickable link to view/edit the just-updated draft in the PostNext dashboard.

⚠️ INLINE-BASE64 PATH — RELIABLE ONLY FOR VERY SMALL FILES (~8KB binary or less). For anything larger, USE request_asset_upload instead — the inline path silently truncates when the base64 string exceeds Claude's context cap for tool args (typically ~10-15KB chars), producing a corrupt image in the library. The pre-signed URL flow has no such cap.

If you do need this: uploads an image or video to your PostNext asset library via base64 and returns a URL for create_post_draft.mediaUrls. Max 5MB per upload (server-side cap; Claude's cap is much lower). Allowed types: JPEG, PNG, WebP, GIF, MP4, WebM. Subject to your plan's storage limit.

IF EVEN THIS PATH FAILS (e.g. your environment can't reach the MCP server at all, OR every upload tool returns a network/allowlist error): tell the user to upload the file manually at https://app.postnext.io/my-assets and paste back the asset URL, then use that URL in create_post_draft.mediaUrls. That's the documented fallback for sandboxes with restricted egress where neither this tool nor request_asset_upload can complete the byte transfer.