Referência de ferramentas
Cada ferramenta que o servidor MCP do PostNext expõe, com suas entradas, estrutura de retorno e um exemplo pronto para copiar e colar.
https://mcp.postnext.io/apiPOST https://mcp.postnext.io/apiAutenticação
Toda requisição para https://mcp.postnext.io/api precisa de um header Authorization com um token Bearer. Você tem duas formas de conseguir um.
OAuth (recomendado para clientes de IA)
Os clientes de IA executam Dynamic Client Registration na primeira conexão e conduzem o usuário por uma tela de consentimento OAuth. A página /mcp/connect faz isso automaticamente. Seu cliente recebe um token de acesso de 30 dias.
Chave de API
Para scripts e CI, gere uma chave de API pessoal no app do PostNext em Conta → Chaves de API. A chave começa com apikey_ e é apresentada como um token Bearer comum.
Endpoint
Todas as chamadas de ferramentas vão para um único endpoint JSON-RPC 2.0 via HTTPS POST.
Ferramentas
list_scheduled_posts
Lista seus posts agendados (na fila para publicação, mas ainda não enviados).
Argumentos
limitfromRetorna
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
limitRetorna
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, providerId, 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
platformwindowDaysRetorna
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
platformcontentchannelNameproviderIdmediaUrlsclientRequestIdRetorna
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 Plano pago
Atualiza um rascunho existente. Pelo menos um dos campos content ou mediaUrls deve ser fornecido.
Argumentos
postIdcontentmediaUrlsclientRequestIdRetorna
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
platformRetorna
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 em um timestamp futuro. Idempotente com variação de até ±60s; recusa reagendar para outro horário sem cancelar antes. Conta para os posts mensais do plano (plano gratuito: 10, compartilhados com o app); cada post conta uma vez, então reagendar depois de um cancelamento ou de uma publicação com falha não conta de novo.
Argumentos
postIdscheduledAtRetorna
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
postIdRetorna
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
postIdRetorna
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
postIdRetorna
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
querystatusplatformlimitRetorna
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. A troca fica salva no documento do token OAuth e vale na hora para as próximas ferramentas da mesma conversa.
Argumentos
teamIdRetorna
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 que alteram dados, para prever se a chamada será bloqueada.
Argumentos
Sem argumentos.
Retorna
Um objeto com tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls cada um como {limit, current, exceeded}; posts como {limit, allowed, current}, onde current é a contagem deste mês, ou null se não pôde ser lida) 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 um post publicado em cada plataforma para a qual foi enviado. O Twitter retorna curtidas, retweets, respostas e impressões; o Instagram retorna curtidas e comentários. LinkedIn, Threads e TikTok retornam só o status da publicação e a URL (a coleta de engajamento virá em uma versão futura). Um total normalizado soma as métricas das plataformas que as informaram.
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 o que aconteceu com um post agendado: status da fila, sucesso ou erro por plataforma, tempo de processamento e jobId do worker. Retorna isScheduled=false para posts que existem como rascunho mas nunca foram movidos para a fila, com uma dica que aponta 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 Plano pago
Atualiza o perfil de marca ativo do usuário. Campos permitidos: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Qualquer outro campo é descartado sem aviso. Define "ativo" primeiro como o perfil padrão da equipe e, se não houver, como o primeiro perfil ativo do próprio 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 alterados] e os valores atuais de bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize após a alteração.
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 N melhores horários (dia da semana, hora) para o próximo post em uma plataforma, com base nos últimos 90 dias. Twitter e Instagram são ordenados por engajamento por post; LinkedIn, Threads e TikTok só pela frequência de publicação. Horários no fuso IANA informado (UTC por padrão). Exige plano pago.
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, Mon=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Inclui hint quando ainda não há histórico ou quando não há 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.
providerId O providerId da conta, vindo de list_connected_accounts. Ele não muda quando o nome de usuário muda, então envie junto com channelName ou no lugar dele.
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 as tags de caso de uso que corresponderam. Grátis em todos os planos (ferramenta de descoberta).
Argumentos
Todos opcionais. Chame sem argumentos para listar todas as ferramentas disponíveis.
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 e currency.
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}}}
import_chat_file
Só no ChatGPT. Salva na sua biblioteca as imagens e vídeos anexados no chat, prontos para create_post_draft. O ChatGPT entrega cada arquivo como um link temporário; o PostNext baixa uma vez por HTTPS e confere no próprio arquivo que é uma imagem ou vídeo. Até 10 arquivos por chamada, 50 MB cada, contando no armazenamento do seu plano (10 MB no total no plano gratuito).
Argumentos
files Preenchido pelo ChatGPT a partir dos arquivos anexados no chat: download_url e file_id, e opcionalmente mime_type e file_name. Até 10. Outros clientes enviam arquivos com request_asset_upload.
Retorna
Um objeto com files (assetId, url, sizeBytes, mimeType e fileName de cada arquivo salvo) e failed (fileName e reason de cada arquivo que não pôde ser salvo). Se nenhum arquivo pôde ser salvo, a chamada devolve o erro do primeiro.
Exemplo
{"jsonrpc":"2.0","method":"tools/call","id":35,
"params":{"name":"import_chat_file",
"arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}
Recursos MCP
Recursos são contexto somente leitura que o cliente pode buscar via método MCP resources/read. O Claude os carrega no início de cada conversa, então tem contexto de conta/equipe/marca sem que você tenha que repetir.
postnext://account/summary
Email e handle da conta (para que o Claude confirme com qual conta está operando), plano, créditos de IA usados / limite, contagem de rascunhos, contagem de agendados, canais conectados. Contagens limitadas a 100 cada para carga rápida.
postnext://channels/connected
Mesma forma que o resultado de list_connected_accounts; exposto como recurso para o Claude carregá-lo uma vez no início da conversa, sem precisar chamar uma ferramenta.
postnext://brand-profiles/active
O perfil de marca ativo do usuário (o padrão da equipe ou, se não houver, o primeiro perfil próprio). Retorna apenas campos relevantes para LLM: bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.
postnext://teams/current
Metadados da equipe atual (teamId, teamName) mais totalTeamsAvailable. Combine com list_teams + set_current_team para trocar.
Fluxos prontos
Atalhos do menu de comandos (/) que combinam várias ferramentas. Escolha um e deixe seu assistente de IA conduzir uma tarefa de várias etapas, pedindo confirmação antes de qualquer alteração.
/weekly-plan
Lê o perfil de marca, os canais conectados e os posts na fila, e propõe de 5 a 10 rascunhos distribuídos de segunda a sexta.
/draft-thread
Escreve uma thread de 5 a 10 posts no Twitter ou no Threads sobre um tema ou URL que você indicar, na voz da sua marca.
/audit-queue
Revisa os posts agendados dos próximos 7 dias e aponta duplicatas, excesso de posts em uma plataforma e lacunas.
/channel-sweep
Compara os canais conectados com as redes compatíveis e sugere quais conectar ou reconectar.
Endpoints de descoberta e OAuth
Metadados em conformidade com padrões para que qualquer cliente MCP se autoconfigure.
GET /.well-known/oauth-protected-resource/api— RFC 9728GET /.well-known/oauth-authorization-server— RFC 8414GET /oauth/.well-known/openid-configuration— OIDCPOST /oauth/reg— Dynamic Client Registration (RFC 7591)GET /oauth/auth— Authorize (PKCE-S256 required)POST /oauth/token— Token exchange
Código aberto
Receitas prontas para colar e uma referência para desenvolvedores estão no nosso repositório público de documentação. Licença MIT; pull requests são bem-vindos. github.com/postnextio/postnext-mcp
MCP de redes sociais para Claude, ChatGPT e qualquer agente de IA
O servidor MCP de redes sociais do PostNext permite que Claude, ChatGPT e qualquer agente de IA planejem, escrevam e agendem posts. Os rascunhos ficam no seu calendário até você agendá-los.