Publish and schedule over MCP

Four tools reach outside Papera: two that publish, and two that manage schedules. This page covers what each one does and the confirmation step they all share.

Before you can publish, the workflow needs a post, at least one connected account wired to it, and a trigger wired to the post. See Build a workflow for how those go together.

The confirmation step

Every tool on this page is called twice:

1. The client calls it without confirm_token. Papera returns a plan describing exactly what would happen, plus a token.
2. The client shows you the plan. If you agree, it calls the same tool again with the same arguments plus the token, and Papera acts.

A token can be used once and expires after ten minutes. It is tied to the exact arguments it was issued for, so if anything changes between the plan and the confirmation you get a fresh plan instead of a surprise.

Publishing the definition

publish_workflow saves a snapshot of the workflow so schedules can run against it. Nothing is posted. This has to happen before you can put a trigger on a schedule.

Posting for real

publish_post posts to the connected accounts. Read its plan closely, for one reason above all:

Confirming fires the whole trigger. Every post that trigger reaches goes out to every account it is connected to, not only the post you named.

The plan tells you:

• each post and account pair, its platform, and how many media items it carries,
• how many accounts will receive the post,
• any post left out because its content could not be read,
• and two side effects: the saved snapshot is replaced by the current draft, and any schedule whose trigger is no longer in the draft stops.

If more than one trigger reaches the post, Papera refuses to choose for you and asks which trigger_id to fire.

Following the outcome

Publishing runs in the background. publish_post returns an occurrence id, and get_publish_status reports each account's outcome as it concludes: the account, whether it published or failed, a link to the live post on success and the reason on failure. Your client polls it until every account is listed.

Re-running the same fire does not post twice.

Scheduling

arm_schedule sets a trigger to fire on a schedule. It needs the trigger id, a first fire time (fire_at, an ISO 8601 date-time) and a recurrence:

Days of the week are numbers, Sunday being 0. Times are wall-clock times in the timezone you name, so a daily post keeps its hour across a clock change. An interval cannot be tighter than five minutes.

The plan spells out the first fire, the cadence and the timezone in words before anything is armed. If the workflow has not been published, arm_schedule refuses and tells you to run publish_workflow first.

disarm_schedule removes a trigger's schedule so it stops firing. Posts that already went out are unaffected, and you can arm it again at any time.

Worked examples

• One post, every account publishes immediately.
• A post every week arms a weekly schedule.