Referência de ferramentas

list_scheduled_posts

Lista seus posts agendados (na fila para publicação, mas ainda não enviados).

Argumentos

Retorna

Um objeto com posts: [{id, platform, content, scheduledAt, status}]. Até limit resultados.

Exemplo

curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'

list_drafts

Lista seus rascunhos (ainda não agendados).

Argumentos

Retorna

Um objeto com drafts: [{id, platform, content, updatedAt}]. Até limit resultados.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}

list_connected_accounts

Lista as contas sociais conectadas à sua equipe.

Argumentos

Sem argumentos.

Retorna

Um objeto com accounts: [{platform, handle, connected, lastSyncAt}].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_healthPlano pago

Obtém um resumo de saúde em todas as plataformas conectadas.

Argumentos

Retorna

Um objeto com windowDays, postsScheduled, postsPublished, postsFailed, um detalhamento byPlatform e topErrors[].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}

create_post_draft

Cria um novo rascunho. Rascunhos não são publicados automaticamente.

Argumentos

Retorna

Um objeto com o novo rascunho: {id, platform, content, status: "DRAFT", createdAt}.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}

update_post_draft

Atualiza um rascunho existente. Pelo menos um dos campos content ou mediaUrls deve ser fornecido.

Argumentos

Retorna

Um objeto com o rascunho atualizado: {id, platform, content, mediaUrls, status, updatedAt}.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}

connect_channel

Gera uma URL de uso único que o usuário pode abrir para autorizar a conexão com uma nova plataforma.

Argumentos

Retorna

Um objeto com authUrl (link de uso único que o usuário abre para autorizar), expiresAt e platform.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}

schedule_post

Move um rascunho (status DRAFT) para a fila de publicação BullMQ em um timestamp futuro. Idempotente dentro de ±60s de drift; rejeita tentativas de reagendamento em outro horário sem cancelamento explícito.

Argumentos

Retorna

Um objeto com postId, scheduledAt (ISO), status: SCHEDULED.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}

cancel_scheduled_post

Cancela uma publicação agendada e a remove da fila. O rascunho subjacente é preservado.

Argumentos

Retorna

Um objeto com postId e status: CANCELLED.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}

delete_draft

Exclui permanentemente um rascunho. Recusa publicações não-DRAFT (use cancel_scheduled_post para SCHEDULED).

Argumentos

Retorna

Um objeto com postId e deleted: true.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}

get_post

Retorna o PostGroup completo para um postId com conteúdo por plataforma + status + timestamps.

Argumentos

Retorna

Um objeto com postId, status, scheduledAt, createdAt, updatedAt e providers (mapa plataforma → conteúdo).

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}

search_posts

Busca de substring (insensível a maiúsculas) no conteúdo de publicações da equipe ativa. Filtros: status, platform, limit (1-100, padrão 20).

Argumentos

Retorna

Um objeto com posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. O snippet contém o contexto correspondente com reticências em ambos os lados.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}

list_teams

Retorna as equipes que o usuário autenticado possui ou administra, com a equipe ativa marcada.

Argumentos

Sem argumentos.

Retorna

Um objeto com currentTeamId e teams: [{teamId, teamName, isCurrent}].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}

set_current_team

Troca a equipe ativa para este token Bearer. O usuário precisa ser membro. Persistido no documento do token OAuth; a mutação em sessão torna efetivo imediatamente para ferramentas seguintes na mesma conversa.

Argumentos

Retorna

Um objeto com teamId, teamName, persisted (true se OAuth, false se API key) e um note opcional.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}

get_plan_limits

Lê o nível de assinatura atual do usuário e as cotas por nível (canais, armazenamento, créditos de IA, publicação). Disponível em todos os planos. Útil antes de ferramentas mutadoras para prever se a chamada será bloqueada.

Argumentos

Sem argumentos.

Retorna

Um objeto com tier, tierDisplayName, isPaid, isTrial, upgradeUrl, limits (channels/storage/aiCalls/posts cada um como {limit, current, exceeded} ou {limit, allowed}) e creditsAvailable ({total, subscriptionRemaining, purchasedBalance} ou null).

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}

get_post_metrics

Busca métricas de engajamento de uma publicação publicada em cada plataforma para a qual foi enviada. Twitter e Instagram retornam métricas populadas (curtidas, retweets/compartilhamentos, comentários/respostas, impressões); LinkedIn, Threads e TikTok retornam apenas status de publicação e URL (a coleta de engajamento foi adiada para uma versão posterior). Um resumo normalizado totals soma curtidas/comentários/compartilhamentos/impressões das plataformas que reportaram.

Argumentos

postId ID do post no PostNext obtido em uma chamada de listagem.

Retorna

Um objeto com postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] e totals: {likes, comments, shares, impressions}. metrics é um objeto de contadores numéricos por plataforma, ou null quando a plataforma ainda não coleta engajamento.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}

get_publish_status

Diagnostica uma publicação agendada: status da fila, sucesso/erro por plataforma, tempo de processamento e jobId do worker. Retorna isScheduled=false para publicações que existem como rascunho mas não foram movidas para a fila, com um hint apontando para schedule_post.

Argumentos

postId ID do post no PostNext obtido em uma chamada de listagem.

Retorna

Um objeto com postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError e results: [{platform, success, publishedPostId, publishedAt, error}]. Inclui hint quando isScheduled é false.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}

update_brand_profile

Atualiza o perfil de marca ativo do usuário. Campos permitidos: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Qualquer outro campo é descartado silenciosamente. Resolve "ativo" primeiro como default da equipe, depois o primeiro perfil ativo próprio do usuário.

Argumentos

brandVoice Array de descritores de voz de marca (ex. ["profissional", "conciso"]).

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

Retorna

Um objeto com profileId, name, updated: [nomes dos campos patchados] e os valores atuais de bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize após o patch.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}

get_best_time_to_post Plano pago

Recomenda os melhores N slots (diaDaSemana, hora) para a próxima publicação em uma plataforma, ordenados por engajamento por publicação dos últimos 90 dias. Twitter e Instagram retornam scores ponderados por engajamento; LinkedIn, Threads, TikTok ordenam apenas por frequência. Horários no fuso IANA informado (UTC por padrão). Plano pago obrigatório.

Argumentos

platform Plataforma social: twitter, instagram, linkedin, threads ou tiktok.

timezone Nome do fuso horário IANA (ex. America/Sao_Paulo, Europe/London). Padrão UTC.

topN Número de recomendações de slots a retornar (1-24, padrão 5).

Retorna

Um objeto com platform, timezone, sampleWindowDays, sampleSize, metricsAvailable e recommendations: [{dayOfWeek (1-7, Seg=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Inclui hint para casos cold-start ou sem métricas disponíveis.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

get_channel_analytics

Desempenho agregado de um canal conectado, ou de todos de uma vez. Devolve impressões, alcance, curtidas, comentários e taxa de engajamento no período, a variação frente ao período anterior de mesma duração e a série de seguidores. Sem platform, vem o total da equipe. Para um post só use get_post_metrics; para planejar, get_best_time_to_post.

Argumentos

platform Plataforma social: twitter, instagram, linkedin, threads ou tiktok.

channelName Qual conta conectada, quando a plataforma tem mais de uma.

period Janela do relatório: 7d, 30d, 90d ou all (padrão 30d).

Retorna

Um objeto com scope, period, totals, vsPrevious, coverage, dataThrough e followers, que traz trackingSince, current, change e a série.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":34,
 "params":{"name":"get_channel_analytics",
           "arguments":{"platform":"linkedin","period":"30d"}}}

search_tools

Pesquisa o catálogo de ferramentas MCP por texto livre, categoria ou intenção. Retorna categorias, requiresScope, descrições de uma linha e os tags de caso de uso que corresponderam. Disponível em qualquer plano (superfície de descoberta).

Argumentos

All optional. Call with no arguments to list every available tool.

query Busca de texto livre em nomes, descrições e tags de uso das ferramentas.

category Filtra para uma categoria: posts, accounts, analytics, brand, teams, discovery, other.

Retorna

Um objeto com totalTools, matchCount, categories: [string[]] e tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Inclui hint quando não há correspondência ou não há filtro.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}

get_plan

Plano e datas de cobrança: nível, data de renovação, fim do teste e se a assinatura está marcada para cancelar no fim do período. Para cotas e uso, chame get_plan_limits.

Argumentos

Sem argumentos.

Retorna

Um objeto com tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd, currency e upgradeUrl.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":21,
 "params":{"name":"get_plan",
           "arguments":{}}}

upload_asset

Envio de imagem ou vídeo para a biblioteca direto em base64. Só é confiável para arquivos bem pequenos, algo como 8 KB ou menos: acima disso o conteúdo é cortado sem aviso nos argumentos da ferramenta e o arquivo salvo fica corrompido. Para qualquer coisa maior, use request_asset_upload.

Argumentos

filename Nome do arquivo com a extensão, até 255 caracteres.

contentType Tipo MIME do arquivo, dentro da lista permitida de imagem e vídeo.

base64 Os bytes do arquivo, codificados em base64. Mantenha bem pequeno e leia antes o aviso acima.

Retorna

Um objeto com assetId, url, sizeBytes e mimeType. Passe a url para create_post_draft em mediaUrls.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":22,
 "params":{"name":"upload_asset",
           "arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}

request_asset_upload

O caminho de envio recomendado, para imagens e vídeos de qualquer tamanho. São dois passos: chame esta ferramenta para receber uma URL pré-assinada e um comando curl pronto, depois envie o arquivo com PUT para essa URL. A resposta do PUT traz a URL final do arquivo.

Argumentos

filename Nome do arquivo com a extensão, até 255 caracteres.

contentType Tipo MIME do arquivo, dentro da lista permitida de imagem e vídeo.

sizeBytes Tamanho exato do arquivo em bytes, usado para assinar o envio.

Retorna

Um objeto com uploadId, uploadUrl, uploadToken, expiresInSeconds e instructions com o comando PUT exato.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":23,
 "params":{"name":"request_asset_upload",
           "arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}

get_latest_blog_post

Se a equipe tem um blog WordPress conectado, junto de um trecho do post mais recente. Somente leitura e sem custo de créditos. Chame antes de create_blog_plan ou test_blog_connection para ver o que já está configurado.

Argumentos

Sem argumentos.

Retorna

Um objeto com blogConnected, um resumo da integração sem credenciais e latestPost com título, trecho, status e URL publicada.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":24,
 "params":{"name":"get_latest_blog_post",
           "arguments":{}}}

list_blog_plans

Lista os planos de blog da equipe, do mais recente para o mais antigo, com status, número de temas por status, créditos reservados e um link para o painel. Somente leitura e sem custo de créditos.

Argumentos

limit Máximo de planos devolvidos (1-50, padrão 20).

status Filtrar por status: generating, active, paused, completed, cancelled ou failed.

Retorna

Um objeto com plans e total. Cada plano traz seu id, status, número de temas e o link do painel.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":25,
 "params":{"name":"list_blog_plans",
           "arguments":{"status":"active","limit":10}}}

create_blog_plan Plano pago

Cria um plano de conteúdo de blog para um perfil de marca. Os temas são gerados de forma assíncrona, então o plano volta na hora com status generating: consulte list_blog_plans para acompanhar. Nos planos Business e Teams os posts também são gerados e publicados em um blog WordPress conectado.

Argumentos

startDate Primeiro dia coberto pelo plano, no formato YYYY-MM-DD.

planDays Quantos dias o plano cobre (1-30, padrão 7).

brandProfileId Perfil de marca a planejar. O padrão é o perfil ativo da equipe.

integrationId Qual blog conectado usar, quando a equipe tem mais de um.

autoPublish Publicar automaticamente os posts gerados no blog conectado (Business e Teams).

Retorna

Um objeto com planId, status, startDate, planDays, brandProfileId, integrationId, topicCount e dashboardUrl.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":26,
 "params":{"name":"create_blog_plan",
           "arguments":{"startDate":"2026-10-01","planDays":14,"autoPublish":true}}}

test_blog_connection Plano pago

Verifica se o blog WordPress conectado responde e se o token dele continua válido, e registra o resultado na integração. Devolve a versão do plugin e o que ele consegue fazer.

Argumentos

integrationId Qual blog conectado usar, quando a equipe tem mais de um.

Retorna

Um objeto com success, message, version, capabilities, integrationId e o status atualizado.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":27,
 "params":{"name":"test_blog_connection",
           "arguments":{}}}

list_mini_sites

Lista as páginas de bio da equipe selecionada, com a URL pública, se estão publicadas e o progresso da configuração. Comece por aqui: todas as outras ferramentas de página de bio usam o siteId devolvido aqui, e podem omiti-lo quando a equipe tem só uma página.

Argumentos

Sem argumentos.

Retorna

Um objeto com sites, cada um com id, slug, name, published, url, views e o progresso da configuração.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":28,
 "params":{"name":"list_mini_sites",
           "arguments":{}}}

get_mini_site

Lê uma página de bio por inteiro: cabeçalho do perfil, ícones sociais, todos os blocos de conteúdo, metadados de SEO, tema e ajustes de auto-pin. Textos longos são cortados numa prévia de 300 caracteres, e credenciais nunca são devolvidas.

Argumentos

siteId Em qual página de bio agir. Omita quando a equipe tem só uma.

Retorna

Um objeto com id, slug, published, url, header, socials, meta, theme, autoPin, campaign e o array blocks.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":29,
 "params":{"name":"get_mini_site",
           "arguments":{}}}

get_mini_site_analytics

Como uma página de bio se sai: visualizações, cliques, melhores links, origem, dispositivo e país dos visitantes, leituras de rastreadores de IA, e quais posts publicados geraram cliques. Todos os números fora as linhas de atribuição são contadores desde sempre, não do período: diga isso ao relatar.

Argumentos

siteId Em qual página de bio agir. Omita quando a equipe tem só uma.

attributionDays Janela em dias para a atribuição de post para clique (1-90, padrão 30).

Retorna

Um objeto com viewsAllTime, clicksAllTime, topLinks, bySource, byDevice, byCountry, ai, attribution e attributionWindowDays.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":30,
 "params":{"name":"get_mini_site_analytics",
           "arguments":{"attributionDays":30}}}

add_mini_site_block

Adiciona um bloco a uma página de bio: link, featured, product, event, presave, episódio de podcast, booking, horários, header, text, image ou gallery. Os campos obrigatórios mudam conforme o tipo. Isso altera na hora uma página visível ao público.

Argumentos

siteId Em qual página de bio agir. Omita quando a equipe tem só uma.

type Tipo de bloco a adicionar, por exemplo link, product, event, hours ou gallery.

... Mais os campos próprios daquele tipo de bloco, por exemplo url, title, price ou startDate.

Retorna

Um objeto com o block salvo, o novo blockCount e alreadyExisted quando esse mesmo bloco já existia.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":31,
 "params":{"name":"add_mini_site_block",
           "arguments":{"type":"link","url":"https://example.com","title":"New single"}}}

update_mini_site_block

Altera um bloco existente: o título ou a URL de um link, o preço de um produto, a data de um evento, os horários ou a ordem de exibição. Só os campos enviados mudam, e o tipo do bloco não pode ser alterado. A resposta devolve o bloco como ficou salvo, então qualquer valor recusado fica visível.

Argumentos

siteId Em qual página de bio agir. Omita quando a equipe tem só uma.

blockId Id do bloco, como devolvido por get_mini_site.

... Mais os campos próprios daquele tipo de bloco, por exemplo url, title, price ou startDate.

Retorna

Um objeto com o block como ficou salvo, a lista de campos atualizados e os ignorados.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":32,
 "params":{"name":"update_mini_site_block",
           "arguments":{"blockId":"blk_7f3a","title":"Updated title"}}}

remove_mini_site_block

Remove um bloco de uma página de bio pelo blockId, por exemplo uma data de turnê que já passou ou um link de produto aposentado. Chame get_mini_site antes para achar o id. Isso altera na hora uma página visível ao público.

Argumentos

siteId Em qual página de bio agir. Omita quando a equipe tem só uma.

blockId Id do bloco, como devolvido por get_mini_site.

Retorna

Um objeto com removed, o blockId e quantos blocos sobraram.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":33,
 "params":{"name":"remove_mini_site_block",
           "arguments":{"blockId":"blk_7f3a"}}}