Tool reference
All 20 tools, their parameters and what they return.
20 tools, and that is the entire surface. Server URL: https://mcp.pressbotics.com/mcp
| Tool | What it does |
|---|---|
| create_connect_link | Creates a one-time link the site owner opens to connect a WordPress site. |
| get_connect_status | Reports whether a connect link has been completed and which site it produced. |
| list_sites | Lists the connected sites the caller is allowed to publish to. |
| get_site_context | Returns a site's handle, capabilities, categories, tags, brand voice notes and approval policy. |
| site_health | Re-probes a site and reports WordPress version, plugin detection and SEO capability. |
| list_content | Lists and filters existing posts on a site so an agent can find something to update. |
| list_media | Lists attachments already in the site's media library, so an existing image can be reused. |
| create_media_upload | Creates an upload link the person opens to hand over a file the agent cannot forward itself. |
| get_media_upload | Polls an upload until it is ready and returns the media_ref to pass to a publish call. |
| publish_post | Creates a post from markdown and publishes it (or queues it for approval). |
| schedule_post | Same as publish_post, plus a future publish_at timestamp. |
| update_post | Updates an existing post by id with new content, taxonomy, media or SEO fields. |
| get_post_status | Returns the current state of a submitted action, including per-component outcomes. |
| list_scheduled | Lists scheduled posts across the caller's sites with their times and current state. |
| reschedule_post | Moves a scheduled post to a new time, on WordPress as well as in Pressbotics. |
| cancel_scheduled | Cancels a scheduled post before it runs, reverting it to a draft on WordPress. |
| schedule_batch | Schedules several posts in one call — a week of content at a time. |
| create_recurrence | Creates a standing cadence that generates empty scheduled slots. It does not write content. |
| list_recurrences | Lists the cadences on a site, with their pattern, timezone and next slots. |
| cancel_recurrence | Stops a cadence generating further slots. Slots already created remain. |
Connecting a site
create_connect_link
Parameters: none required. Returns a one-time URL for the site owner to open, and an id to poll. The agent never handles the WordPress credential itself.
get_connect_status
Parameters: the connect link id. Returns whether it has been completed and, once it has, the resulting site handle.
Sites
list_sites
Parameters: none. Returns the sites the caller may publish to, each with its handle. A key scoped to specific sites sees only those.
get_site_context
Parameters: site. Returns the handle, approval policy, existing categories and tags, brand voice notes and SEO capability. Call it before the first publish of a session.
site_health
Parameters: site. Re-probes the live site: WordPress version, companion plugin detection, SEO capability, reachability. Use after installing a plugin or when something that worked stops.
Finding things
list_content
Parameters: site, plus any of the filters below. Returns posts with id, title, status, date and modified — the dates are what make "the post I published last Tuesday" resolvable.
| Filter | Type | Meaning |
|---|---|---|
| search | string | Free-text search across post titles and content. |
| category | string | Category name. |
| tag | string | Tag name. |
| status | string | Accepted, but list_content only returns published posts today. Drafts and scheduled posts are not listed. |
| published_after | ISO 8601 or YYYY-MM-DD | Only posts published on or after this moment. |
| published_before | ISO 8601 or YYYY-MM-DD | Only posts published before this moment. |
| order_by | date | title | modified | Sort field. |
| order | asc | desc | Sort direction. |
| page | number | 1-based page number. |
| limit | number | Results per page. |
list_media
Parameters: site, plus search and pagination. Returns attachments already in the media library with their ids, filenames, MIME types and URLs. The id is what you pass as featured_image_id.
The media handoff
create_media_upload
Parameters: site, and optionally purpose and note describing what the file is for. Returns upload_id, an upload_url for the person to open, and expires_at 60 minutes out. The URL is a signed-in Pressbotics page, not a raw storage link.
get_media_upload
Parameters: upload_id. Returns status (pending, ready, expired or failed), and when ready a media_ref plus filename, mime_type and size. Pass the media_ref as featured_media_ref. An upload_id from another workspace returns not found.
Publishing
publish_post, schedule_post and update_post share these parameters. publish_at is schedule_post only; post_id is update_post only and required there.
| Parameter | Type | Notes |
|---|---|---|
| site | string | Site handle or URL. Required. |
| title | string | Post title — the on-page headline. Required. |
| markdown | string | Post body in markdown. Converted to Gutenberg blocks. Required. |
| excerpt | string | WordPress excerpt. Does NOT set the meta description. |
| categories | string[] | Category names (not ids). Matched by name or created. |
| tags | string[] | Tag names (not ids). Matched by name or created. |
| featured_image_url | string (URL) | Public URL. Downloaded and sideloaded as the featured image. |
| featured_image_id | number | An attachment id already in the media library. Find one with list_media. |
| featured_media_ref | string | A file the person uploaded through the media handoff. From get_media_upload. |
| seo_title | string | The title tag. Max 70 characters. Needs the companion plugin + an SEO plugin (Yoast verified; Rank Math supported, untested). |
| meta_description | string | The search-result description. Max 200 characters. Same plugin requirement. |
| focus_keyword | string | Max 120 characters. Same plugin requirement. |
| canonical_url | string (URL) | Canonical link for the post. |
| request_review | boolean | Force the post into the approval queue regardless of site policy. |
| idempotency_key | string | Required. Repeat calls with the same key return the original action instead of duplicating. |
| publish_at | ISO 8601 | schedule_post only. Future publish time. |
| post_id | number | update_post only. The WordPress post to update. Required there. |
The three image inputs are mutually exclusive
| Parameter | Source | Behaviour |
|---|---|---|
| featured_image_url | A publicly reachable URL | Pressbotics downloads it and sideloads it into the media library, then sets it as the featured image. |
| featured_image_id | An attachment already on the site | Reuse something in the media library. Find the id with list_media. |
| featured_media_ref | A file the person just uploaded | Produced by the media upload handoff: create_media_upload, the person uploads, get_media_upload returns the ref. |
Supplying more than one image input is rejected. Pressbotics never silently picks one.
get_post_status
Parameters: the action id returned by a publish, schedule or update call. Returns the current state — queued, published, published (partial), scheduled, failed, rejected or reverted — with the same per-component fields below.
Scheduling
Seven tools cover scheduled posts and standing cadences. Scheduling and recurrence require a paid plan; on Free they return plan_upgrade_required.
| Tool | Parameters | Returns |
|---|---|---|
| list_scheduled | site (optional), from / to (ISO 8601, optional), status (optional), page, limit | Scheduled posts with schedule_id, title, site, publish_at (absolute UTC), status (scheduled, published, cancelled, missed) and wp_post_id where known. |
| reschedule_post | schedule_id (required), publish_at (ISO 8601 with offset, required) | The updated row. Pressbotics only records the move after WordPress confirms it; a failure returns a code such as wp_reschedule_unverified and changes nothing. |
| cancel_scheduled | schedule_id (required) | The cancelled row. The WordPress post reverts to a draft. Cancelling an already-cancelled item returns already_cancelled rather than issuing a second call. |
| schedule_batch | site (required), posts[] — each an ordinary schedule_post payload with its own publish_at | One result per item, each with its own action id and outcome. Items are independent: one can fail while the rest schedule. |
| create_recurrence | site, days_of_week, time_of_day, timezone, ends_on — see the table below | The cadence, plus the slots generated for the horizon ahead. |
| list_recurrences | site (optional) | Each cadence with its id, pattern, timezone, end date and whether it is active. |
| cancel_recurrence | recurrence_id (required) | The cancelled cadence. Future slots stop being generated; slots already scheduled are untouched and must be cancelled individually. |
A publish_at or ends_on with no timezone information is REJECTED, not guessed. Send an ISO 8601 timestamp with an offset, or — for a cadence — the explicit IANA timezone below.
create_recurrence takes flat fields
| Parameter | Type | Notes |
|---|---|---|
| site | string | Site handle or URL. Required. |
| days_of_week | number[] | 0 = Sunday through 6 = Saturday. Required. [1,3,5] is Monday, Wednesday, Friday. |
| time_of_day | "HH:MM" | 24-hour local time in the timezone below, e.g. "09:00". Required. |
| timezone | IANA timezone | REQUIRED — e.g. "America/New_York". There is no default and no guess. |
| ends_on | YYYY-MM-DD | Optional. Without it the cadence runs until you cancel it. |
A recurrence schedules SLOTS, not content. It never writes a post. The pattern is: create the cadence, then fill its slots with schedule_batch. A cadence with nothing behind it produces empty slots and nothing publishes.
create_recurrence({
site: "myblog",
days_of_week: [1, 3, 5],
time_of_day: "09:00",
timezone: "America/New_York",
ends_on: "2026-12-31"
})Response contract
Every executed publish, schedule or update returns these. Read them before telling anyone it worked: a post can go live without its featured image, and the response says so.
| Field | Values | Meaning |
|---|---|---|
| state | queued | published | scheduled | failed | rejected | reverted | What happened to the post itself. Everything below describes its components. |
| partial | boolean | True when the post landed but at least one component did not. |
| image_status | none | ok | failed | Featured image outcome. |
| image_error | string | Why the featured image failed, when it did. |
| taxonomy_status | none | ok | partial | failed | Categories and tags outcome. |
| taxonomy_error | string | Which terms could not be applied. |
| seo_status | none | ok | unsupported | Whether SEO meta was actually written. |
| seo_error | string | Which piece is missing when seo_status is "unsupported". |
| embed_status | none | ok | partial | failed | Whether provider embeds resolved. A provider that will not embed stays a plain link and the post still publishes. |
| embeds | array | The embed URLs found and what each became. |
| inline_images | { total, failed, errors } | Inline image re-hosting. An image that cannot be fetched is REMOVED from the post body and listed in errors; the post still publishes. |
| post_url | string (URL) | The live post URL, once it exists. |
| render_check | pass | fail | not_yet | pass: the live post was fetched and rendered correctly. fail: it did not, and the post was reverted to draft. not_yet: a scheduled post that is not public yet — the scheduler verifies it when it goes live and writes pass or fail then. |