---
title: "Tool reference | PostNext"
description: "Every tool the PostNext MCP server exposes, with its inputs, return shape and a copy-paste example. Social media scheduler for 7 networks, by PostNext."
url: "https://postnext.io/mcp/docs"
language: "en-GB"
---

# Tool reference

Every tool the PostNext MCP server exposes, with its inputs, return shape and a copy-paste example. Social media scheduler for 7 networks, by PostNext.

Human version: [https://postnext.io/mcp/docs](https://postnext.io/mcp/docs)

Every tool the PostNext MCP server exposes, with its inputs, return shape and a copy-paste example.

[Connect PostNext](https://postnext.io/mcp/connect)

MCP server URL `https://mcp.postnext.io/api`

```
POST https://mcp.postnext.io/api
```

## Authentication

Every request to https://mcp.postnext.io/api requires an Authorization header with a Bearer token. You have two ways to get one.

### OAuth (recommended for AI clients)

AI clients run Dynamic Client Registration on first connect, then walk the user through an OAuth consent screen. The /mcp/connect page handles this automatically. Your client receives a 30-day access token.

### API key

For scripts and CI, generate a personal API key in the PostNext app under Account → API Keys. The key starts with apikey\_ and is presented as a bearer token like any other.

### Endpoint

All tool calls go to a single JSON-RPC 2.0 endpoint over HTTPS POST.

POST https://mcp.postnext.io/api

## Tools

### `list_scheduled_posts`

List your scheduled posts (queued for publish but not yet sent).

#### Arguments

`limit` number ·optional · default 20

Maximum results to return (1-100, default 20).

`from` string (ISO 8601) ·optional

ISO timestamp; only return posts scheduled at or after this time.

#### Returns

An object with posts: \[{id, platform, content, scheduledAt, status}\]. Up to limit results.

#### Example

```
curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'
```

### `list_drafts`

List your draft posts (not yet scheduled).

#### Arguments

`limit` number ·optional · default 20

Maximum results to return (1-100, default 20).

#### Returns

An object with drafts: \[{id, platform, content, updatedAt}\]. Up to limit results.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}
```

### `list_connected_accounts`

List the social accounts connected to your team.

#### Arguments

No arguments.

#### Returns

An object with accounts: \[{platform, handle, providerId, connected, lastSyncAt}\].

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}
```

### `get_account_health` Paid plan

Get a health summary across all connected platforms.

#### Arguments

`platform` enum ·optional

Social platform: twitter, instagram, linkedin, threads, or tiktok.

`windowDays`7 | 30 | 90 ·optional · default 30

Lookback window in days: 7, 30 or 90 (default 30).

#### Returns

An object with windowDays, postsScheduled, postsPublished, postsFailed, a byPlatform breakdown and topErrors\[\].

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}
```

### `create_post_draft`

Create a new draft post. Drafts are not auto-published.

#### Arguments

`platform` enum ·required

Social platform: twitter, instagram, linkedin, threads, or tiktok.

`content` string ·required

Post body (1-2200 characters).

`channelName` string ·optional

Which connected account, when the platform has more than one.

`providerId` string ·optional

The account's providerId from list\_connected\_accounts. It stays the same when the handle changes, so pass it with or instead of channelName.

`mediaUrls` array<string> ·optional

Up to 10 image/video URLs.

`clientRequestId` string ·optional

Optional idempotency key. Same key within 5 minutes returns the cached result.

#### Returns

An object with the new draft: {id, platform, content, status: "DRAFT", createdAt}.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}
```

### `update_post_draft` Paid plan

Update an existing draft. At least one of content or mediaUrls must be provided.

#### Arguments

`postId` string ·required

PostNext post id from a list call.

`content` string ·optional

Post body (1-2200 characters).

`mediaUrls` array<string> ·optional

Up to 10 image/video URLs.

`clientRequestId` string ·optional

Optional idempotency key. Same key within 5 minutes returns the cached result.

#### Returns

An object with the updated draft: {id, platform, content, mediaUrls, status, updatedAt}.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}
```

### `connect_channel`

Generate a one-time URL the user can open to authorize a new platform connection.

#### Arguments

`platform` enum ·required

Social platform: twitter, instagram, linkedin, threads, or tiktok.

#### Returns

An object with authUrl (one-time link the user opens to authorise), expiresAt and platform.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}
```

### `schedule_post`

Move a draft (status DRAFT) into the publish queue at a future timestamp. Idempotent within ±60s drift; rejects re-schedule attempts at a different time without explicit cancel first. Counts against the plan's monthly posts (Free: 10, shared with the app); a post counts once, so rescheduling it after a cancel or a failed publish is not counted again.

#### Arguments

`postId` string ·required

PostNext post id from a list call.

`scheduledAt` string (ISO 8601) ·required

ISO 8601 timestamp; must not be more than 5 minutes in the past.

#### Returns

An object with postId, scheduledAt (ISO), status: SCHEDULED.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}
```

### `cancel_scheduled_post`

Cancel a scheduled post and remove it from the publish queue. The underlying draft is preserved.

#### Arguments

`postId` string ·required

PostNext post id from a list call.

#### Returns

An object with postId and status: CANCELLED.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}
```

### `delete_draft`

Permanently delete a draft post. Refuses non-DRAFT posts (use cancel\_scheduled\_post for SCHEDULED).

#### Arguments

`postId` string ·required

PostNext post id from a list call.

#### Returns

An object with postId and deleted: true.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}
```

### `get_post`

Return the full PostGroup for a given postId with provider-by-platform content + status + timestamps.

#### Arguments

`postId` string ·required

PostNext post id from a list call.

#### Returns

An object with postId, status, scheduledAt, createdAt, updatedAt and providers (record of platform → content).

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}
```

### `search_posts`

Substring (case-insensitive) search across post content for the active team. Filters: status, platform, limit (1-100, default 20).

#### Arguments

`query` string ·required

Substring to search for (3-200 characters; regex meta-chars are escaped).

`status` enum ·optional

Optional: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.

`platform` enum ·optional

Social platform: twitter, instagram, linkedin, threads, or tiktok.

`limit` number ·optional · default 20

Maximum results to return (1-100, default 20).

#### Returns

An object with posts: \[{postId, status, platforms, snippet, scheduledAt, updatedAt}\]. Snippet contains the matching context with ellipsis on either side.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}
```

### `list_teams`

Return the teams the authenticated user owns or admins, with the currently active team flagged.

#### Arguments

No arguments.

#### Returns

An object with currentTeamId and teams: \[{teamId, teamName, isCurrent}\].

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}
```

### `set_current_team`

Switch the active team for this Bearer token. The user must be a member. Persisted on the OAuth token doc; in-session mutation makes it effective immediately for subsequent tools in the same conversation.

#### Arguments

`teamId` string ·required

Target teamId from list\_teams. Membership is re-validated server-side.

#### Returns

An object with teamId, teamName, persisted (true if OAuth, false if API key) and an optional note.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}
```

### `get_plan_limits`

Read the user's current subscription tier and per-tier quotas (channels, storage, AI credits, posting). Available on every plan. Useful before mutating tools to predict whether the call will be blocked.

#### Arguments

No arguments.

#### Returns

An object with tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls each as {limit, current, exceeded}; posts as {limit, allowed, current}, where current is this month's count, or null if it could not be read) and creditsAvailable ({total, subscriptionRemaining, purchasedBalance} or null).

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}
```

### `get_post_metrics`

Fetch engagement metrics for a published post across every platform it was sent to. Twitter returns likes, retweets, replies and impressions; Instagram returns likes and comments. LinkedIn, Threads and TikTok return publish status and URL only (engagement collection deferred to a later release). A normalised totals roll-up sums the metrics across whichever platforms reported them.

#### Arguments

`postId` PostNext post id from a list call.

#### Returns

An object with postId, status, providers: \[{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}\] and totals: {likes, comments, shares, impressions}. metrics is an object of numeric counts per platform, or null when the platform does not yet collect engagement.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}
```

### `get_publish_status`

Diagnose what happened to a scheduled post: queue state, per-platform success/error, processing time, and the worker's job id. Returns isScheduled=false for posts that exist as drafts but were never moved into the publish queue, with a hint pointing at schedule\_post.

#### Arguments

`postId` PostNext post id from a list call.

#### Returns

An object with postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError, and results: \[{platform, success, publishedPostId, publishedAt, error}\]. Includes hint when isScheduled is false.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}
```

### `update_brand_profile` Paid plan

Patch the user's active brand profile. Whitelisted fields: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Anything else is silently dropped. Resolves "active" as team default first, then the user's first own active profile.

#### Arguments

`brandVoice` Array of brand-voice descriptors (e.g. \["professional", "concise"\]).

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

#### Returns

An object with profileId, name, updated: \[field names that were patched\], and the current values of bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize after the patch.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}
```

### `get_best_time_to_post` Paid plan

Recommend the top N (dayOfWeek, hour) slots for the next post on a given platform, from the past 90 days. Twitter and Instagram rank by engagement per post; LinkedIn, Threads and TikTok rank by post frequency only. Times are in the supplied IANA timezone (default UTC). Paid plan required.

#### Arguments

`platform` Social platform: twitter, instagram, linkedin, threads, or tiktok.

`timezone` IANA timezone name (e.g. Europe/Berlin, America/New\_York). Defaults to UTC.

`topN` Number of slot recommendations to return (1-24, default 5).

#### Returns

An object with platform, timezone, sampleWindowDays, sampleSize, metricsAvailable, and recommendations: \[{dayOfWeek (1-7, Mon=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}\]. Includes hint for cold-start or metrics-unavailable cases.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}
```

### `get_channel_analytics`

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. Use get\_post\_metrics for a single post and get\_best\_time\_to\_post for scheduling.

#### Arguments

`platform` Social platform: twitter, instagram, linkedin, threads, or tiktok.

`channelName` Which connected account, when the platform has more than one.

`providerId` The account's providerId from list\_connected\_accounts. It stays the same when the handle changes, so pass it with or instead of channelName.

`period` Window to report on: 7d, 30d, 90d or all (default 30d).

#### Returns

An object with scope, period, totals, vsPrevious, coverage, dataThrough and followers, which carries trackingSince, current, change and the series.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":34,
 "params":{"name":"get_channel_analytics",
           "arguments":{"platform":"linkedin","period":"30d"}}}
```

### `search_tools`

Search the MCP tool catalog by free-text query, category, or intent. Returns categories, requiresScope, one-line descriptions, and the use-case tags that matched. Free for all plans (discovery surface).

#### Arguments

All optional. Call with no arguments to list every available tool.

`query` Free-text search across tool names, descriptions, and use-case tags.

`category` Filter to one category: posts, accounts, analytics, brand, teams, discovery, other.

#### Returns

An object with totalTools, matchCount, categories: \[string\[\]\], and tools: \[{name, category, requiresScope, description, useCases, matchedOn: \[name|category|description|use\_case\]}\]. Includes hint when no match or no filter.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}
```

### `get_plan`

Plan identity and billing dates: tier, renewal date, trial end date, and whether the subscription is set to cancel at the period end. For quotas and usage, call get\_plan\_limits instead.

#### Arguments

No arguments.

#### Returns

An object with tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd and currency.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":21,
 "params":{"name":"get_plan",
           "arguments":{}}}
```

### `upload_asset`

Inline base64 upload of an image or video to the asset library. Reliable only for very small files, around 8KB or less: a larger payload silently truncates in the tool arguments and stores a corrupt file. Use request\_asset\_upload for anything bigger.

#### Arguments

`filename` File name including its extension, up to 255 characters.

`contentType` MIME type of the file, from the allowed image and video list.

`base64` The file bytes, base64 encoded. Keep this tiny, and read the warning above first.

#### Returns

An object with assetId, url, sizeBytes and mimeType. Pass the url to create\_post\_draft as mediaUrls.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":22,
 "params":{"name":"upload_asset",
           "arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}
```

### `request_asset_upload`

The recommended upload path, for images and video of any size. Two steps: call this tool to get a pre-signed URL and a ready-made curl command, then PUT the file bytes to that URL. The PUT response carries the final asset URL.

#### Arguments

`filename` File name including its extension, up to 255 characters.

`contentType` MIME type of the file, from the allowed image and video list.

`sizeBytes` Exact size of the file in bytes, used to sign the upload.

#### Returns

An object with uploadId, uploadUrl, uploadToken, expiresInSeconds and instructions holding the exact PUT command.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":23,
 "params":{"name":"request_asset_upload",
           "arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}
```

### `import_chat_file`

ChatGPT only. Saves images and videos attached in the chat to your asset library, ready for create\_post\_draft. ChatGPT hands each file over as a temporary link; PostNext downloads it once over HTTPS and checks from the file itself that it is an image or video. Up to 10 files per call, 50 MB each, counted against your plan's storage (10 MB in total on Free).

#### Arguments

`files` Filled in by ChatGPT from the files attached in the chat: download\_url and file\_id, optionally mime\_type and file\_name. Up to 10. Other clients upload with request\_asset\_upload.

#### Returns

An object with files (assetId, url, sizeBytes, mimeType and fileName for each saved file) and failed (fileName and reason for each file that could not be saved). If no file could be saved, the call returns the first file's error instead.

#### Example

```
{"jsonrpc":"2.0","method":"tools/call","id":35,
 "params":{"name":"import_chat_file",
           "arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}
```

## MCP Resources

Resources are read-only context the client can fetch via the MCP resources/read method. Claude pulls them at conversation start so it has account/team/brand context without you re-asking each session.

### `postnext://account/summary`

Account email and handle (so Claude can confirm which account it's operating on), plan, AI credits used / limit, draft count, scheduled count, connected channel count. Counts capped at 100 each for fast load.

### `postnext://channels/connected`

Same shape as list\_connected\_accounts result; exposed as a resource so Claude pulls it once at conversation start (no tool-call round-trip).

### `postnext://brand-profiles/active`

The user's active brand profile (team default, falling back to first own profile). Returns only LLM-relevant fields: bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.

### `postnext://teams/current`

Current team metadata (teamId, teamName) plus totalTeamsAvailable count. Pair with list\_teams + set\_current\_team to switch.

## Named workflows

Slash-menu shortcuts that orchestrate multiple tools. Pick one and let your AI assistant walk through a multi-step task with confirmation before mutating anything.

### `/weekly-plan`

Read brand profile, connected channels and queued posts, then propose 5-10 drafts spread Monday to Friday.

### `/draft-thread`

Write a 5-10 post Twitter or Threads thread on a topic or URL you supply, in your brand voice.

### `/audit-queue`

Walk the next 7 days of scheduled posts and flag duplicates, platform overload, and gaps.

### `/channel-sweep`

Compare connected channels against the supported set and suggest which to connect or refresh.

## Discovery and OAuth endpoints

Standards-compliant metadata so any MCP client can auto-configure.

- `GET /.well-known/oauth-protected-resource/api` — RFC 9728
- `GET /.well-known/oauth-authorization-server` — RFC 8414
- `GET /oauth/.well-known/openid-configuration` — OIDC
- `POST /oauth/reg` — Dynamic Client Registration (RFC 7591)
- `GET /oauth/auth` — Authorize (PKCE-S256 required)
- `POST /oauth/token` — Token exchange

## Open source

Paste-ready recipes and a developer-facing reference live in our public docs repo. MIT-licensed; pull requests welcome. [github.com/postnextio/postnext-mcp](https://github.com/postnextio/postnext-mcp)

## Social media MCP for Claude, ChatGPT and any AI agent

PostNext's social media MCP server lets Claude, ChatGPT and any AI agent plan, draft and schedule posts. Drafts wait in your calendar until you schedule them.

[Open in Claude Desktop](https://postnext.io/mcp/connect)
