Tools

All uPubly MCP server tools — input schemas, outputs and examples.

Calls via tools/call on the POST /mcp endpoint. All accept an optional workspace_id (uuid) — omitted uses the user's default workspace.

Posts

post_accounts_list

Lists connected social accounts — discovers the account_id for scheduling.

{ "workspace_id": "optional" }

→ { "accounts": [{ "account_id", "platform", "username" }] }

post_list

Lists posts (templates) with their schedules.

{ "workspace_id": "?", "page": 0, "size": 20, "search": "optional" }

post_create

Creates a post and, if schedules is present, schedules the publication right away. Without schedules it becomes a draft.

{
  "description": "Main post text",
  "caption": "Caption (optional)",
  "name": "Internal name (optional)",
  "media": ["file_id_1", "file_id_2"],
  "schedules": [
    {
      "account_id": "account uuid (post_accounts_list)",
      "scheduled_at": "2026-09-25T14:00:00-03:00",
      "post_type": "feed|reels|story|video (inferred if omitted)"
    }
  ]
}

media takes file_ids from Storage (see storage_request_upload).

post_delete

{ "post_id": 123 }

Storage

Upload is presigned in 2 steps:

storage_request_upload

{
  "file_name": "banner.png",
  "content_type": "image/png (inferred if omitted)",
  "file_size": 1024,
  "folder_id": "optional"
}

→ { "upload_url", "file_id", "upload_id", ... }. PUT the binary to upload_url and then confirm:

storage_complete_upload

{ "file_id": "...", "upload_id": "...", "parts": [{ "part_number": 1, "etag": "..." }] }

storage_usage

→ bytes used vs plan limit.

media_upload_from_url

One-call shortcut: downloads an image from a public http(s) URL and uploads it to storage — returns file_id (the media_id used in refs/avatars/scenes) + file_url. Max 20MB; for larger files or local bytes use the presigned path.

{ "url": "https://.../image.png", "file_name": "optional" }

Brand (brain)

Always read brand_get before proposing changes — it returns the full state (identity, visual identity, memory).

Niche, audience and positioning do not live in the identity: they live in the Manifesto (brand_manifest_update_section). The mainNiche, secondaryNiches, primaryGoal and workspaceType fields of brand_get come back empty.

brand_update_identity

{ "brand_name": "...", "language": "pt-BR", "region": "...", "website": "...", "active_platforms": ["instagram"] }

brand_manifest_get

The Manifesto is the document that says who the brand is, and it is what the AI reads when it generates content. Seven sections: identity (what it is, niche), audience, positioning (differentiator), what_we_argue (theses), voice (tone), limits (what not to do) and subjects.

{ "sections": ["identity", "positioning"] }

Omit sections to read all of them.

brand_manifest_update_section

Writes a new version of one section. The text replaces the current content and the history stays. The version is marked as written by the AI.

{ "section": "identity", "content": "full section text" }

brand_briefing_get / brand_briefing_update_block

Briefing (Business Map). Blocks: objetivo_do_negocio, como_ganha_dinheiro, cliente, mercado, comercial, marketing. A write sets the block state and appends answers:

{
  "block": "cliente",
  "state": "confirmed|inferred|unknown",
  "answers": [{ "text": "...", "kind": "fact", "confidence": "high" }]
}

brand_vocabulary_list / brand_vocabulary_upsert / brand_vocabulary_delete

Terms approved, dont_use (with replacement) and use_carefully. The upsert is a batch: with id it updates, without id it creates.

{ "terms": [{ "term": "customer", "category": "dont_use", "replacement": "partner" }] }

brand_update_visual_identity

{
  "primary_color": "#FF5500", "secondary_color": "...", "accent_color": "...",
  "font_display": "...", "font_body": "...", "tagline": "...",
  "logo_file_id": "storage file_id"
}

brand_update_memory

Creator memory — what the AI learned about the style:

{
  "preferred_angles": ["..."], "weak_angles": ["..."],
  "preferred_cta": ["..."], "avoid_cta": ["..."],
  "avg_retention": 42.5, "content_stats": { "...": "free-form" }
}

brand_add_document

Document in the knowledge base (RAG) — brand guide, strategy, manifesto, research:

{
  "document_type": "brand_guide|brand_voice|strategy|manifesto|market_research|script|report|reference|high_performance|low_performance",
  "title": "...",
  "content": "plain text",
  "file_url": "file URL (storage)",
  "source_url": "optional", "metadata": {}
}

brand_documents_list / brand_document_delete

Lists the knowledge-base documents (limit, offset) and removes one by document_id. The indexed chunks go with it.

Billing

plans_list

→ { "plans": [...], "topup": { ... } } — active plans with monthly/yearly pricing in BRL, monthly credits, trial days and the accepted cycles (billing_cycles).

  • Plan credits: Pro 8,000 a month (up to 3,000 for image, video and voice); Max 20,000 a month (up to 8,000 for media). Basic has no monthly credits.
  • Trial: 500 credits on every plan, Basic included.
  • topup — the top-up rules: { "by_value": true, "currency": "BRL", "methods": { "pix": { "min_brl", "bonus_percent" }, "card": { "min_brl", "bonus_percent" } } }. Top-up credits are bought by value in R$, in the app, by the workspace owner: from R$ 10 with Pix and R$ 20 with card, with +3% credits on Pix. The purchase screen shows how many credits the amount buys. Top-up credits never expire and have no media cap. There is no top-up link through MCP.

Creates the checkout (payment link) for the user to subscribe to a plan:

{ "plan_id": "plan id (plans_list)", "billing_cycle": "monthly|yearly" }

→ { "checkout_url", "session_id" } — send checkout_url to the client so they can complete the subscription. Prices always come from the server-side catalog — the agent never injects values.

credits_balance

The user's credit balance — check before operations that debit credits (UGC jobs, avatar/scene generation):

→ { "monthly_balance", "topup_balance", "total_balance", "monthly_allowance", "cycle_started_at", "cycle_ends_at", "plan_name", "member_limit", "scope", "media_cap", "media_used" }

  • monthly_balance — the plan credits. They renew every cycle.
  • topup_balance — the top-up credits. They never expire.
  • media_cap / media_used — how much of the plan credits can go to image, video and voice in the cycle, and how much is used. null = no cap. Pro caps media at 3,000 credits; Max at 8,000. Past the cap, media comes out of the top-up credits, which have no media cap.
  • member_limit — { "limit", "used", "resets_at" } when the user has a personal limit in the workspace. With scope: "member" the balances are what is left of that limit.

Details and error codes: UGC — Generation.

UGC (avatars, scenes, generation)

The ugc_* namespace — models, estimate, async jobs, avatars, scenes, templates and projects — has its own reference: UGC — Generation · Avatars · Video generation.