Tool reference

POST https://popkit.loxily.com/api/mcp
Authorization: Bearer <token>
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: create_post
Accept: application/json, text/event-stream
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "create_post",
    "arguments": {
      "action": "schedule",
      "scheduledAt": "2026-09-20T10:00:00+08:00",
      "content": "…", "platforms": ["x", "youtube"],
      "clientRequestId": "acme-2026-09-20-001"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "acme-scheduler", "version": "1.4.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    } } }

• 2026 clients have no handshake — your first message can be tools/list. 2025-era clients send initialize first; same URL, the server answers in their dialect.
• Mcp-Method is required on every request. Add Mcp-Name for tools/call and prompts/get (= params.name) and for resources/read (= params.uri). A mismatch is 400 -32020.
• The _meta envelope needs protocolVersion and clientCapabilities, both prefixed io.modelcontextprotocol/; clientInfo is optional but recommended — it shows up in the workspace audit trail.
• Accept should list both application/json and text/event-stream: 2026 calls normally answer as plain JSON, but 2025-era calls are answered as SSE.
• Tool output is in structuredContent. A business failure is still HTTP 200 with isError: true; the machine code sits in _meta["com.popkit/error"].code.

Workspace & accounts

Reading content

Writing content

Publishing

Comments

Idea board

Analytics

Prompt templates package popkit's playbooks — the data is fetched and the rules are baked in, so the model does not have to be told twice. Resources are cacheable read-only snapshots. Both are pruned by scope, exactly like tools.

• Publishing is asynchronous — create_post / confirm_publish return { postId, status: "publishing", deepLink } right away; poll get_post for per-account results. Stuck for ~15 minutes counts as failed.
• Which accounts — targetAccountIds omitted means *every usable account* on the requested platforms (expired ones are skipped silently), capped at 20 per call. Pass it explicitly to choose. On update_post, omitting the field keeps the existing selection.
• Idempotency — write tools take clientRequestId (8–128 chars of [A-Za-z0-9_.:-]). A replay within 24 h returns the original result flagged _meta["com.popkit/replayed"]; it is required on the publish tier. The key is bound to the arguments: reuse it with different arguments and you get invalid_input.
• Rate limits, each counted over a different scope: read 60 / write 10 / publish 5 per minute per credential × workspace × tool; 20 outbound publishes per day per credential × workspace; 600 s between two publishes to the same account per workspace — that last one is shared, so several credentials posting to one account throttle each other. Over any of them → rate_limited with retryAfterSec.
• Comment replies are counted separately. The daily publish cap and the same-account interval do not apply to them — replying to a batch of comments is normal use and must not be throttled by quotas designed for posting content. The one limit that does apply: a single comment accepts at most 3 replies from you per 24 h (counted per platform comment, shared across workspaces), which bounds force; and 500 replies per day per credential × workspace as a backstop. Over it → rate_limited with params.reason = "comment_reply_cap".
• Manual channels (Douyin / Xiaohongshu / WeChat MP) have no platform API: publish only records the post and reminds an admin to paste it — nothing goes out automatically.
• Media cannot be an external link. Call attach_media first (direct upload or transload) to get a mediaUrl, then pass it as media[].dataUrl.

What each failure means: Errors & fixes. What a credential is allowed to do: Auth & security.