Todas as tools do servidor MCP do uPubly — schemas de input, outputs e exemplos.
Chamadas via tools/call no endpoint POST /mcp. Todas aceitam
workspace_id opcional (uuid) — omitido usa o workspace default do usuário.
post_accounts_listLista as contas de rede social conectadas — descobre o account_id para
agendar.
{ "workspace_id": "opcional" }→ { "accounts": [{ "account_id", "platform", "username" }] }
post_listLista posts (templates) com seus agendamentos.
{ "workspace_id": "?", "page": 0, "size": 20, "search": "opcional" }post_createCria um post e, se schedules vier, já agenda a publicação. Sem
schedules vira rascunho.
{
"description": "Texto principal do post",
"caption": "Legenda (opcional)",
"name": "Nome interno (opcional)",
"media": ["file_id_1", "file_id_2"],
"schedules": [
{
"account_id": "uuid da conta (post_accounts_list)",
"scheduled_at": "2026-09-25T14:00:00-03:00",
"post_type": "feed|reels|story|video (inferido se omitido)"
}
]
}media recebe file_ids do Storage (ver storage_request_upload).
post_delete{ "post_id": 123 }O upload é presignado em 2 passos:
storage_request_upload{
"file_name": "banner.png",
"content_type": "image/png (inferido se omitido)",
"file_size": 1024,
"folder_id": "opcional"
}→ { "upload_url", "file_id", "upload_id", ... }. Faça PUT do binário na
upload_url e depois confirme:
storage_complete_upload{ "file_id": "...", "upload_id": "...", "parts": [{ "part_number": 1, "etag": "..." }] }storage_usage→ bytes usados vs limite do plano.
media_upload_from_urlAtalho de uma chamada: baixa uma imagem de URL pública http(s) e sobe no
storage — devolve file_id (o media_id usado em refs/avatares/cenários)
file_url. Máx 20MB; acima disso ou bytes locais → caminho presignado.{ "url": "https://.../imagem.png", "file_name": "opcional" }Sempre leia brand_get antes de propor mudanças — ele devolve o estado
completo (identidade, identidade visual, memória).
Nicho, público e posicionamento não ficam na identidade: moram no
Manifesto (brand_manifest_update_section). Os campos mainNiche,
secondaryNiches, primaryGoal e workspaceType do brand_get voltam
vazios.
brand_update_identity{ "brand_name": "...", "language": "pt-BR", "region": "...", "website": "...", "active_platforms": ["instagram"] }brand_manifest_getO Manifesto é o documento que diz quem a marca é, e é o que a IA lê ao gerar
conteúdo. Sete seções: identity (o que é, nicho), audience (público),
positioning (diferencial), what_we_argue (teses), voice (tom),
limits (o que não fazer) e subjects (assuntos).
{ "sections": ["identity", "positioning"] }Omita sections para ler todas.
brand_manifest_update_sectionGrava uma versão nova de uma seção. O texto substitui o conteúdo vigente e o histórico fica. A versão sai marcada como escrita pela IA.
{ "section": "identity", "content": "texto completo da seção" }brand_briefing_get / brand_briefing_update_blockBriefing (Mapa do Negócio). Blocos: objetivo_do_negocio,
como_ganha_dinheiro, cliente, mercado, comercial, marketing. A
escrita define o estado do bloco e acrescenta respostas:
{
"block": "cliente",
"state": "confirmed|inferred|unknown",
"answers": [{ "text": "...", "kind": "fact", "confidence": "high" }]
}brand_vocabulary_list / brand_vocabulary_upsert / brand_vocabulary_deleteTermos approved, dont_use (com replacement) e use_carefully. O upsert
é em lote: com id atualiza, sem id cria.
{ "terms": [{ "term": "cliente", "category": "dont_use", "replacement": "parceiro" }] }brand_update_visual_identity{
"primary_color": "#FF5500", "secondary_color": "...", "accent_color": "...",
"font_display": "...", "font_body": "...", "tagline": "...",
"logo_file_id": "file_id do storage"
}brand_update_memoryMemória do criador — o que a IA aprendeu do estilo:
{
"preferred_angles": ["..."], "weak_angles": ["..."],
"preferred_cta": ["..."], "avoid_cta": ["..."],
"avg_retention": 42.5, "content_stats": { "...": "livre" }
}brand_add_documentDocumento na base de conhecimento (RAG) — guia de marca, estratégia, manifesto, pesquisa:
{
"document_type": "brand_guide|brand_voice|strategy|manifesto|market_research|script|report|reference|high_performance|low_performance",
"title": "...",
"content": "texto puro",
"file_url": "URL de arquivo (storage)",
"source_url": "opcional", "metadata": {}
}brand_documents_list / brand_document_deleteLista os documentos da base (limit, offset) e remove um pelo
document_id. Os trechos indexados saem junto.
plans_list→ { "plans": [...], "topup": { ... } } — planos ativos com preço
mensal/anual em BRL, créditos mensais, dias de trial e os ciclos aceitos
(billing_cycles).
topup — as regras dos créditos avulsos:
{ "by_value": true, "currency": "BRL", "methods": { "pix": { "min_brl", "bonus_percent" }, "card": { "min_brl", "bonus_percent" } } }.
O avulso é comprado por valor em R$, no app, pelo dono do workspace: a
partir de R$ 10 no Pix e R$ 20 no cartão, com +3% de créditos no Pix. A
tela de compra mostra quantos créditos o valor rende. Créditos avulsos
não vencem e não têm limite de mídia. Não há link de avulso pelo MCP.payment_link_createCria o checkout (link de pagamento) para o usuário assinar um plano:
{ "plan_id": "id do plano (plans_list)", "billing_cycle": "monthly|yearly" }→ { "checkout_url", "session_id" } — envie checkout_url ao cliente
para ele concluir a assinatura. Preços sempre vêm do catálogo server-side —
o agente nunca injeta valores.
credits_balanceSaldo de créditos do usuário — consulte antes de operações que debitam (jobs UGC, geração de avatar/cenário):
→ { "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 — os créditos do plano. Renovam a cada ciclo.topup_balance — os créditos avulsos. Não vencem.media_cap / media_used — quanto dos créditos do plano pode ir para
imagem, vídeo e voz no ciclo, e quanto já foi. null = sem limite. No
Pro o limite é 3.000 créditos; no Max, 8.000. Passou do limite, a mídia
sai dos créditos avulsos, que não têm limite de mídia.member_limit — { "limit", "used", "resets_at" } quando o usuário tem
um limite próprio no workspace. Com scope: "member" os saldos são o que
sobra desse limite.Detalhes e códigos de erro: UGC — Geração.
O namespace ugc_* — modelos, estimativa, jobs async, avatares, cenários,
templates e projetos — tem referência própria:
UGC — Geração · Avatares ·
Geração de vídeo.