Pular para o conteúdo

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.

URL do servidor MCPhttps://mcp.postnext.io/api
POST https://mcp.postnext.io/api

Autenticaçã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.

POST https://mcp.postnext.io/api

Ferramentas

list_scheduled_posts

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

Argumentos

limitnumber ·opcional · default 20
Número máximo de resultados a retornar (1-100, padrão 20).
fromstring (ISO 8601) ·opcional
Timestamp ISO; retorna apenas posts agendados neste horário ou depois dele.

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

limitnumber ·opcional · default 20
Número máximo de resultados a retornar (1-100, padrão 20).

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, 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

platformenum ·opcional
Plataforma social: twitter, instagram, linkedin, threads ou tiktok.
windowDays7 | 30 | 90 ·opcional · default 30
Janela de análise em dias: 7, 30 ou 90 (padrão 30).

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

platformenum ·obrigatório
Plataforma social: twitter, instagram, linkedin, threads ou tiktok.
contentstring ·obrigatório
Corpo do post (1-2200 caracteres).
channelNamestring ·opcional
Qual conta conectada, quando a plataforma tem mais de uma.
providerIdstring ·opcional
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.
mediaUrlsarray<string> ·opcional
Até 10 URLs de imagens ou vídeos.
clientRequestIdstring ·opcional
Chave de idempotência opcional. A mesma chave dentro de 5 minutos retorna o resultado em cache.

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 Plano pago

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

Argumentos

postIdstring ·obrigatório
ID do post no PostNext obtido em uma chamada de listagem.
contentstring ·opcional
Corpo do post (1-2200 caracteres).
mediaUrlsarray<string> ·opcional
Até 10 URLs de imagens ou vídeos.
clientRequestIdstring ·opcional
Chave de idempotência opcional. A mesma chave dentro de 5 minutos retorna o resultado em cache.

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

platformenum ·obrigatório
Plataforma social: twitter, instagram, linkedin, threads ou tiktok.

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 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

postIdstring ·obrigatório
ID do post no PostNext obtido em uma chamada de listagem.
scheduledAtstring (ISO 8601) ·obrigatório
Timestamp ISO 8601; não pode estar mais de 5 minutos no passado.

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

postIdstring ·obrigatório
ID do post no PostNext obtido em uma chamada de listagem.

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

postIdstring ·obrigatório
ID do post no PostNext obtido em uma chamada de listagem.

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

postIdstring ·obrigatório
ID do post no PostNext obtido em uma chamada de listagem.

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

querystring ·obrigatório
Substring para buscar (3-200 caracteres; metacaracteres regex são escapados).
statusenum ·opcional
Opcional: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.
platformenum ·opcional
Plataforma social: twitter, instagram, linkedin, threads ou tiktok.
limitnumber ·opcional · default 20
Número máximo de resultados a retornar (1-100, padrão 20).

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. A troca fica salva no documento do token OAuth e vale na hora para as próximas ferramentas da mesma conversa.

Argumentos

teamIdstring ·obrigatório
teamId de destino, vindo de list_teams. O servidor confere de novo se você é membro da equipe.

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 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 9728
  • GET /.well-known/oauth-authorization-server — RFC 8414
  • GET /oauth/.well-known/openid-configuration — OIDC
  • POST /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.