MCP
MCP tools
Every tool the server offers, its parameters, the scope that unlocks it, and whether it writes.
Tool names are a contract, like REST paths: they never change meaning within v1. The publishing tools carry the names agents already know, so a prompt written for another publishing server works here unchanged. Every tool answers the same payload the REST route would, in both the text block and structuredContent.
tools/list returns only the tools the key is scoped for. Write tools take an optional idempotencyKey; see Idempotency.
Publishing
list_connections
List connected social accounts. Scope connections:read, read-only.
Every connected account with tokenStatus, lastError and lastSuccessfulPost. Call it first to get the connectionIds that create_post needs. An expired connection must be reconnected in the app.
list_posts
List posts. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
status | enum | draft, scheduled, publishing, published, partial_published, failed, cancelled |
platform | string | One platform id |
from, to | ISO 8601 | Window on scheduledAt |
page | integer | Default 1 |
limit | integer | Default 50, max 200 |
Newest first, paginated; read total before saying how many there are.
create_post
Create a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
content | string | Required, 1 to 10,000 characters |
connectionIds | string[] | Required, 1 to 20 |
scheduledAt | ISO 8601 | Omit for a draft |
mediaUrls | string[] | Up to 10 public https URLs |
mediaIds | string[] | Up to 10, from complete_media |
platformSettings | object | Per-platform settings keyed by platform |
variants | object | { [platform]: { content } } |
requireApproval | boolean | Queue for approval anyway |
idempotencyKey | string | Up to 255 characters |
Same rules as POST /posts: Instagram needs media, unknown settings are refused with PLATFORM_SETTING_UNKNOWN, and the approval rule applies with an APPROVAL_REQUIRED warning.
get_post
Get one post. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
One post with targets. A failed target carries the platform error verbatim.
update_post
Edit a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
| … | Every create_post field, all optional | |
idempotencyKey | string |
Only the fields passed change. POST_NOT_EDITABLE once the post is publishing, published or cancelled.
delete_post
Cancel a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
idempotencyKey | string |
Cancel a draft or scheduled post; the row is kept as cancelled. Nothing is removed from any platform.
get_upload_url
Get a media upload URL. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
kind | enum | image or video, required |
contentType | string | Required |
bytes | integer | Required, exact length |
idempotencyKey | string |
A presigned PUT valid for 15 minutes (15 MB images, 500 MB video). PUT the bytes, then complete_media, then pass the id as mediaIds.
complete_media
Complete a media upload. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
mediaId | uuid | Required |
idempotencyKey | string |
Confirms the upload landed. MEDIA_NOT_READY if the bytes are not there yet.
delete_media
Delete a media asset. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
mediaId | uuid | Required |
idempotencyKey | string |
Deletes the asset and its object. Only delete media no post still needs.
get_best_times
Get best posting times. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
platform | string | Optional |
Slots from the workspace's own history plus per-platform priors; fromHistory says which.
post_stats
Get engagement for a published post. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
Delivery facts per target plus an engagement block. engagement is null with an unavailableReason when there is no reading; today that is the case on every deployment where platform-derived reads are off, and for every platform other than Facebook and Instagram.
profile_stats
Get profile stats for a connected account. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
connectionId | uuid | Required |
The connection, its delivery record from our own log (publishedPosts, lastSuccessfulPost, lastError), and insights, which is null with an unavailableReason under the same conditions as post_stats.
Workflows and Gloofy
list_workflows
List workflows. Scope workflows:run, read-only.
The workspace's automations: id, name, description, enabled, autonomy, triggers, templateKey, updatedAt. A disabled workflow can still be run manually.
run_workflow
Run a workflow. Scope workflows:run, writes.
| Parameter | Type | Notes |
|---|---|---|
workflowId | uuid | Required |
dryRun | boolean | Walk data and condition nodes, report what would be staged |
triggerMeta | object | Exposed to nodes as {{trigger.*}} |
idempotencyKey | string |
Queues a manual run and returns { runId, workflowId, status, dryRun }. Refused with plan_limit_reached when the daily run cap is used up, and with a budget message when the monthly AI budget is spent.
get_workflow_run
Get a workflow run. Scope workflows:run, read-only.
| Parameter | Type | Notes |
|---|---|---|
runId | uuid | Required |
Status (queued, running, succeeded, failed, skipped), times, costMicros (null until finished), summary, error and the steps in order. A step that staged an action for a human to confirm says so; it has not been performed.
ask_gloofy
Ask Gloofy. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
question | string | Required, up to 4,000 characters |
One grounded answer from the workspace's assistant, with toolsUsed and any stagedActions. Costs model budget against the workspace, the same as chatting in the app. Staged actions have not been performed.
Analytics
list_ad_accounts
List connected ad accounts. Scope analytics:read, read-only.
The ad accounts this workspace connected, each with its metrics-sync state.
get_metrics_summary
Get ad metrics totals. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | Both or neither; default last 30 days |
accountId | uuid | Optional |
Totals over a window. Money in minor units as a string; null counters are missing readings.
list_daily_metrics
List ad metrics by day. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | |
accountId | uuid | |
limit | integer | Default 500, max 2,000 |
Per-day totals, newest first, split by account, platform and currency.
list_crawled_sites
List crawled sites. Scope analytics:read, read-only.
Sites overads crawls for this workspace, each with a crawl block.
list_crawled_pages
List crawled pages. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
siteId | uuid | |
limit | integer | Default 200, max 1,000 |
Tracked URLs and how the last visit ended. Twelve state values; only the fetched_* ones say anything about the page.
get_page_timeline
Get one page visit history. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
pageId | uuid | Required |
limit | integer | Default 200, max 500 |
Every visit, newest first, including the ones that returned nothing.
list_page_changes
List detected page changes. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
siteId | uuid | |
pageId | uuid | |
limit | integer | Default 100, max 500 |
Visits where a detector fired, with before and after strings. Check provenance.emptyMeans before reading an empty list as no change.
list_instagram_profiles
List tracked Instagram profiles. Scope analytics:read, read-only. Gated: Absent from tools/list unless the deployment enables platform-derived sources.
Tracked handles and the last reading of each. Counts are null when Instagram withheld them.