---
title: "Referência de ferramentas | PostNext"
description: "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: "https://postnext.io/pt-br/mcp/docs"
language: "pt-BR"
---

# Referência de ferramentas

Human version: [https://postnext.io/pt-br/mcp/docs](https://postnext.io/pt-br/mcp/docs)

Cada ferramenta que o servidor MCP do PostNext expõe, com suas entradas, estrutura de retorno e um exemplo pronto para copiar e colar.

[Conectar o PostNext](https://postnext.io/pt-br/mcp/connect)

URL do servidor MCP `https://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

`limit` number ·opcional · default 20

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

`from` string (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

`limit` number ·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_health` Plano pago

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

#### Argumentos

`platform` enum ·opcional

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

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

`platform` enum ·obrigatório

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

`content` string ·obrigatório

Corpo do post (1-2200 caracteres).

`channelName` string ·opcional

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

`providerId` string ·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.

`mediaUrls` array<string> ·opcional

Até 10 URLs de imagens ou vídeos.

`clientRequestId` string ·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

`postId` string ·obrigatório

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

`content` string ·opcional

Corpo do post (1-2200 caracteres).

`mediaUrls` array<string> ·opcional

Até 10 URLs de imagens ou vídeos.

`clientRequestId` string ·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

`platform` enum ·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

`postId` string ·obrigatório

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

`scheduledAt` string (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

`postId` string ·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

`postId` string ·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

`postId` string ·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

`query` string ·obrigatório

Substring para buscar (3-200 caracteres; metacaracteres regex são escapados).

`status` enum ·opcional

Opcional: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.

`platform` enum ·opcional

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

`limit` number ·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

`teamId` string ·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](https://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.

[Abrir no Claude Desktop](https://postnext.io/pt-br/mcp/connect)
