MCP Tools Reference

This page lists every tool the OneUp MCP server provides, with its exact name and required parameters. It also explains how to call the server directly if you are building your own MCP client instead of using ChatGPT, Claude, or a coding agent.

If you only use OneUp through an AI assistant, you don't need to call these tools yourself. The assistant picks the right tool from your request.

Tool Names

Call tools by their exact name. Names use hyphens and end in -tool, for example get-tiktok-overview-tool. The one exception is get_published_posts.

If you call a name that doesn't exist, the server returns:

{ "code": -32602, "message": "Tool [get_tiktok_overview] not found." }

The authoritative list is always the response of tools/list (see below).

Calling the Server Directly

The server speaks MCP over HTTP (JSON-RPC 2.0) at:

https://feed.oneupapp.io/mcp/oneup?apiKey=YOUR_API_KEY

Keep this URL private, because it contains your API key. To connect with OAuth instead, see the coding agents setup guide.

1. Initialize a session

curl -i -X POST "https://feed.oneupapp.io/mcp/oneup?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-portal","version":"1.0.0"}}}'

Copy the Mcp-Session-Id response header and send it on every following request.

2. List the tools

curl -X POST "https://feed.oneupapp.io/mcp/oneup?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tip

The tool list can be split into pages. If the response contains a nextCursor, request the next page by sending "params": {"cursor": "<nextCursor value>"}, and repeat until no nextCursor is returned. Clients that only read the first page may miss tools.

3. Call a tool

curl -X POST "https://feed.oneupapp.io/mcp/oneup?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get-tiktok-overview-tool","arguments":{"social_network_id":"YOUR_SOCIAL_ACCOUNT_ID","preset":"last_30_days"}}}'

A successful call returns the data in structuredContent (and the same data as JSON text in content):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"data\":{...}}" }],
    "isError": false,
    "structuredContent": { "data": { "...": "..." } }
  }
}

If the request can't be completed, for example because of an invalid date, isError is true and content explains what to fix:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "The end_date must be yesterday or earlier (UTC). Analytics for today are not available yet." }
    ],
    "isError": true
  }
}

Rate Limit

The MCP server accepts up to 60 requests per minute. If you fetch data for many accounts, for example in a nightly sync, request them one after another instead of all at once.

Accounts

Use these tools to find the account IDs that other tools need. The social_account_id returned by list-social-accounts-tool is the value to pass as social_network_id or social_account_id in other tools.

Tool	Required parameters	What it does
`list-categories-tool`	–	Lists your categories (groups of social accounts).
`list-social-accounts-tool`	–	Lists all connected social accounts on every platform.
`list-category-accounts-tool`	`category_id`	Lists the accounts in one category.

tip

If you manage several clients, create one category per client. You can then use list-category-accounts-tool to get each client's accounts.

Posts

Tool	Required parameters	What it does
`schedule-text-post-tool`	`category_id`, `social_network_id`, `scheduled_date_time`, `content`	Schedules a text post.
`schedule-image-post-tool`	`category_id`, `social_network_id`, `scheduled_date_time`, `content`	Schedules an image post.
`schedule-video-post-tool`	`category_id`, `social_network_id`, `scheduled_date_time`, `content`	Schedules a video post.
`get-scheduled-posts-tool`	–	Lists scheduled posts.
`get-scheduled-posts-by-id-tool`	`post_ids`	Gets specific scheduled posts by ID.
`get_published_posts`	–	Lists published posts.
`get-failed-posts-tool`	–	Lists posts that failed to publish, with the reason.
`get-draft-posts-tool`	–	Lists draft posts.
`edit-post-tool`	`post_id`, `content`	Edits the title or content of a scheduled or draft post.
`delete-scheduled-post-tool`	`post_id`	Deletes a scheduled post.
`reschedule-failed-post-tool`	`post_id`, `scheduled_date_time`	Retries a failed post at a new time.
`fetch-pinterest-boards-tool`	`pinterest_username`	Lists Pinterest boards (required for Pinterest posts).
`fetch-you-tube-playlists-tool`	`social_account_id`	Lists a YouTube channel's playlists.
`get-tiktok-trending-sound-tool`	`social_account_id`, `country_code`, `date_range`, `genre`	Lists trending TikTok sounds.
`get-instagram-trending-sound-tool`	`social_account_id`	Lists trending Instagram sounds.

Post dates use YYYY-MM-DD HH:MM (24-hour), for example 2026-12-25 14:30.

The post list tools return the post content, dates, and media. They don't include likes, views, or comments. For performance numbers per post, use the analytics posts tools below.

Comments

Tool	Required parameters	What it does
`fetch-top-comments-tool`	–	Lists posts with their comments.
`fetch-comment-replies-tool`	`comment_id`	Lists replies to a comment.
`reply-to-post-tool`	`platform`, `post_id`, `comment`, `social_account_id`	Posts a new comment on a post.
`reply-to-comment-tool`	`platform`, `post_id`, `parent_comment_id`, `comment`, `social_account_id`	Replies to a comment.
`delete-comment-tool`	`platform`, `post_id`, `comment_id`, `social_account_id`	Deletes a comment.
`force-refresh-comments-tool`	–	Pulls new comments from the connected platforms.

Tool	Required parameters	What it does
`fetch-conversations-tool`	`social_account_id`	Lists conversations for one Facebook, Instagram, or WhatsApp account.
`fetch-conversation-messages-tool`	`id`	Lists messages in a conversation.
`send-message-tool`	`id`, `message`	Sends a reply in a conversation.
`mark-conversation-read-tool`	`id`	Marks a conversation's messages as read.
`update-conversation-status-tool`	`id`, `status`	Sets a conversation to open, closed, or spam.
`force-refresh-conversations-tool`	`social_account_id`	Refreshes recent Facebook or Instagram conversations.
`load-more-conversations-tool`	`social_account_id`	Loads more Facebook or Instagram conversations.
`fetch-whats-app-accounts-tool`	–	Lists connected WhatsApp business numbers.
`fetch-whats-app-contacts-tool`	`social_account_id`	Lists saved WhatsApp contacts.
`fetch-whats-app-templates-tool`	`social_account_id`	Lists approved WhatsApp templates.
`create-whats-app-conversation-tool`	`social_account_id`, `whatsapp_contact_id`, `whatsapp_template_id`	Starts a WhatsApp conversation with a template.

Analytics

warning

Analytics tools are not available on the Basic plan. Upgrade to Intermediate, Growth or Business plan to use them.

All analytics tools take the same parameters:

Parameter	Required	Description
`social_network_id`	Yes	The account's `social_account_id` from `list-social-accounts-tool`. One account per call.
`preset`	Required without dates	`last_7_days`, `last_30_days`, or `last_90_days`.
`start_date`	Required without `preset`	Start date in `YYYY-MM-DD` format.
`end_date`	Required without `preset`	End date in `YYYY-MM-DD` format. Must be on or after `start_date` and no later than yesterday (UTC). Today's analytics aren't available yet.
`timezone`	No	A PHP timezone identifier, for example `Europe/Amsterdam`. Default: `UTC`.

The Facebook and Instagram overview tools also accept separate_stories (true or false) to report stories separately from posts.

Analytics tools return data OneUp has already collected. They don't contact the social platforms directly. Use force-refresh-analytics-tool to ask OneUp to refresh analytics for all your connected accounts.

The data returned in structuredContent.data matches the data field of the Analytics API. See the linked platform pages for the fields in each response.

Platform	Tools	Response fields
Facebook	`get-facebook-overview-tool`, `get-facebook-posts-tool`, `get-facebook-reels-tool`, `get-facebook-stories-tool`, `get-facebook-demographics-tool`	Facebook Analytics
Instagram	`get-instagram-overview-tool`, `get-instagram-posts-tool`, `get-instagram-stories-tool`, `get-instagram-demographics-tool`	Instagram Analytics
TikTok	`get-tiktok-overview-tool`, `get-tiktok-posts-tool`, `get-tiktok-demographics-tool`	TikTok Analytics
YouTube	`get-youtube-overview-tool`, `get-youtube-posts-tool`, `get-youtube-demographics-tool`	YouTube Analytics
LinkedIn	`get-linked-in-overview-tool`, `get-linked-in-posts-tool` (organization accounts only)	LinkedIn Analytics
Google Business Profile	`get-gbp-overview-tool`, `get-gbp-posts-tool`, `get-gbp-reviews-tool`	Google Business Profile Analytics
Meta Ads	`get-meta-ads-overview-tool`, `get-meta-ads-campaigns-tool`, `get-meta-ads-ad-sets-tool`, `get-meta-ads-ads-tool`	Meta Ads Analytics
Threads	`get-threads-overview-tool`, `get-threads-posts-tool`	Threads Analytics
Pinterest	`get-pinterest-overview-tool`, `get-pinterest-posts-tool`	Pinterest Analytics
Snapchat	`get-snapchat-overview-tool`, `get-snapchat-posts-tool`	Snapchat Analytics
Bluesky	`get-bluesky-overview-tool`, `get-bluesky-posts-tool`	Bluesky Analytics

Overview tools return account totals compared with the previous period, plus top and bottom posts. Posts tools return per-post metrics such as views, likes, comments, and shares. Demographics tools return audience breakdowns such as age, gender, and location.

Example

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get-instagram-posts-tool",
    "arguments": {
      "social_network_id": "YOUR_SOCIAL_ACCOUNT_ID",
      "start_date": "2026-10-01",
      "end_date": "2026-10-31",
      "timezone": "Europe/Amsterdam"
    }
  }
}

Common Errors

Message	What to do
`Tool [...] not found.`	Check the tool name against this page or `tools/list`.
`The end_date must be yesterday or earlier (UTC)...`	Use an earlier `end_date`, or use a `preset`.
`The end_date must be on or after start_date.`	Make sure `end_date` is not before `start_date`.
`The timezone must be a valid PHP timezone identifier...`	Use a name like `Europe/Amsterdam` or `America/New_York`.
`No connected ... account was found for this social_network_id...`	Use an ID from `list-social-accounts-tool`. If you just connected the account, run `force-refresh-analytics-tool` and try again shortly.
`The ... account token has expired. Please reconnect the account.`	Reconnect the account in OneUp.
`Analytics isn't included in the Basic plan...`	Upgrade to a plan that includes analytics.

Tool Names​

Calling the Server Directly​

1. Initialize a session​

2. List the tools​

3. Call a tool​

Rate Limit​

Accounts​

Posts​

Comments​

Social Inbox​

Analytics​

Example​

Common Errors​