Servidor MCP do Flux
O Flux expõe um servidor MCP (Model Context Protocol). Depois de conectá-lo, você conversa com o Flux em português dentro do Claude, do ChatGPT, do Cursor ou do n8n: pergunta o que está agendado e, com os escopos de escrita, monta, agenda e publica posts pelo chat, sem escrever código.
Por baixo, as ferramentas seguem a mesma API pública v1 do Flux, com a mesma credencial, os mesmos escopos e o mesmo alcance de projetos. O que muda é a forma de pedir.
Endereço do servidor
https://flux.reportei.com/mcp/v1O v1 do MCP é independente do v1 da API REST: o conjunto de ferramentas pode evoluir sem que o contrato REST mude, e vice-versa.
O que dá para perguntar
Pergunte pelo resultado que você quer, não pela ferramenta.
O que está travado esperando decisão de revisor? Qual é o mais urgente?
O que sai essa semana no cliente Padaria Aurora?
Me mostra a legenda completa do post 4471.
Essa peça foi publicada em quais redes?
Alguma conta conectada está com a autorização expirada?
Monta um rascunho com a foto que te mandei, para o Instagram e o Facebook da Padaria Aurora.
Agenda esse post para sexta às 9h.
Marca como aprovados os posts desse pacote.
O modelo escolhe as ferramentas e as encadeia sozinho: descobre o id do projeto antes de filtrar posts por data, por exemplo. Você não precisa citar nome de ferramenta nem id. Antes de agendar ou publicar, o assistente mostra o que vai sair e pede a sua confirmação.
Conectar o servidor
Há dois caminhos, e o certo depende do cliente. Clientes de assistente com conector fazem OAuth sozinhos: você cola a URL e autoriza. Clientes de terminal e de automação usam um token no header. Abaixo, o que vale para todos; depois, o passo a passo de cada cliente.
OAuth (conector)
Você cola a URL do servidor, entra com a conta do Reportei, escolhe a conta e as permissões e autoriza. Nenhum token passa pelas suas mãos.
Token no header
Você emite o token na tela do Flux e o informa no header Authorization do cliente.
A URL do servidor
É o mesmo endereço para todos os clientes, com OAuth ou com token. Cole exatamente assim, sem barra no fim: um caractere de diferença derruba a conexão sem mensagem útil.
https://flux.reportei.com/mcp/v1Escopos e o que cada um libera
Os escopos são escolhidos na tela de consentimento do Reportei (OAuth) ou na emissão do token, e definem quais ferramentas o cliente enxerga.
| Escopo | Concede |
|---|---|
| projects:read | flux_list_projects |
| posts:read | flux_list_posts, flux_get_post, flux_get_content_group, flux_get_week_overview, flux_find_blocked_content |
| reviews:read | flux_list_post_reviews, flux_list_review_groups, flux_get_review_group |
| integrations:read | flux_list_connected_accounts, flux_list_pinterest_boards, flux_list_tiktok_privacy_options, flux_review_tiktok_settings, flux_list_youtube_options |
| media:write | flux_prepare_media_upload, flux_import_media_from_url, flux_import_media_from_chat, flux_get_media |
| posts:create | flux_create_post, flux_create_pinterest_board |
| posts:update | flux_update_post, flux_publish_post |
| reviews:create | flux_mark_review_status |
Para escrever, conceda os escopos de escrita
As ferramentas de escrita só aparecem quando a credencial tem o escopo delas. No OAuth, a tela de consentimento mostra os escopos que o cliente pediu, e você pode desmarcar o que não quer conceder; se o cliente não pedir nenhum, a tela oferece só os de leitura. Conectou e as ferramentas de escrita não aparecem? Desconecte e conecte de novo marcando as permissões de escrita, ou use um token no header com esses escopos.
O alcance é o de quem autoriza
A credencial nasce com o alcance de projetos de quem autorizou, naquela conta: ela não fica maior do que a pessoa que a criou. Revogar o acesso de alguém a um projeto não revoga as credenciais que já emitiu. Ao desligar uma pessoa, revogue também as credenciais dela.
A credencial do conector vale 30 dias e é renovada sozinha pelo cliente, sem pedir nova autorização. Ela aparece em Empresa → API e MCP, junto dos tokens, e pode ser revogada ali.
Se o seu cliente usa token no header
Clientes de terminal e de automação aceitam uma chave em cabeçalho. Use o mesmo token flux_ da API REST, emitido em Empresa → API e MCP, com os escopos de escrita, se o cliente for criar conteúdo: /company/edit/api
A descoberta, se você quiser ver
O documento de Protected Resource Metadata (RFC 9728) é público e lido antes de existir qualquer credencial. É ele que diz ao cliente quem autoriza o recurso.
curl -s https://flux.reportei.com/.well-known/oauth-protected-resourceClaude
OAuthNo Claude, o Flux entra como conector personalizado. O consentimento acontece no navegador e a credencial fica guardada do lado do Claude: você não copia token nenhum.
- 1Abra Configurações → Conectores e escolha adicionar um conector personalizado.
- 2Cole a URL do servidor MCP do Flux e confirme.
- 3O Claude abre a tela de consentimento do Reportei: entre com a sua conta, escolha qual conta (company) autorizar e quais escopos conceder.
- 4De volta ao Claude, o conector aparece com as ferramentas do Flux. Ative-o na conversa e pergunte.
Libere o domínio do Flux para enviar mídias
Para o Claude enviar imagens e vídeos ao Flux, acesse Configurações → Recursos, ative Permitir acesso de rede externo e inclua o domínio abaixo em Domínios adicionais permitidos. Depois, abra uma conversa nova.
flux.reportei.comSem isso, o envio de arquivo falha com erro de rede (por exemplo, "Could not resolve host"). As demais ferramentas do Flux funcionam normalmente.
redirect_uri aceita
https://claude.ai/api/mcp/auth_callbackÉ a única redirect_uri que o Flux aceita para este cliente. Se a conexão falhar com erro de redirect_uri, o cliente está usando outra. Avise o suporte informando qual.
ChatGPT
OAuthNo ChatGPT, o Flux entra como conector personalizado. Criar conectores próprios depende do plano e pode precisar estar habilitado para a sua conta ou workspace.
- 1Abra Configurações → Conectores e escolha criar um conector.
- 2Cole a URL do servidor MCP do Flux e escolha OAuth como forma de autenticação.
- 3Autorize na tela do Reportei: conta e escopos.
- 4Ative o conector na conversa para que o ChatGPT use as ferramentas do Flux.
redirect_uri aceita
https://chatgpt.com/connector_platform_oauth_redirectÉ a única redirect_uri que o Flux aceita para este cliente. Se a conexão falhar com erro de redirect_uri, o cliente está usando outra. Avise o suporte informando qual.
Grok
OAuthNo Grok, o Flux entra como conector personalizado. O percurso é o mesmo: descoberta a partir da URL, consentimento no navegador e credencial guardada do lado do cliente.
- 1Acesse grok.com/connectors, clique em New Connector e escolha Custom.
- 2Cole a URL do servidor MCP do Flux e confirme.
- 3Autorize na tela do Reportei: conta e escopos.
- 4Volte ao Grok e confira que as ferramentas do Flux aparecem no conector.
redirect_uri aceita
https://grok.com/connectors-oauth-exchange-code/É a única redirect_uri que o Flux aceita para este cliente. Se a conexão falhar com erro de redirect_uri, o cliente está usando outra. Avise o suporte informando qual.
Perplexity
OAuthNo Perplexity, o Flux entra pela tela de conectores. O percurso é o mesmo: descoberta a partir da URL, consentimento no navegador e credencial guardada do lado do cliente.
- 1Abra Configurações → Conectores e escolha adicionar um conector.
- 2Cole a URL do servidor MCP do Flux e confirme.
- 3Autorize na tela do Reportei: conta e escopos.
- 4Volte ao Perplexity e confira que as ferramentas do Flux aparecem no conector.
redirect_uri aceita
https://www.perplexity.ai/rest/connections/oauth_callbackÉ a única redirect_uri que o Flux aceita para este cliente. Se a conexão falhar com erro de redirect_uri, o cliente está usando outra. Avise o suporte informando qual.
Claude Code
Token no headerCliente de terminal: o servidor é registrado por comando, com o token no header. claude mcp é comando do terminal, não um slash command. Rode fora da sessão do Claude Code.
- 1Emita um token em Empresa → API e MCP, com os escopos que você quer expor.
- 2Registre o servidor no terminal, trocando flux_SEU_TOKEN pelo token emitido.
- 3Abra uma sessão nova: o servidor é carregado na inicialização, então uma sessão que já estava aberta não o vê.
- 4Dentro da sessão, /mcp deve mostrar flux conectado, com as ferramentas listadas.
claude mcp add --transport http flux https://flux.reportei.com/mcp/v1 \
--header "Authorization: Bearer flux_SEU_TOKEN"O registro fica no escopo local por padrão, e local aqui significa aquela pasta: um servidor registrado em ~/projetos/x não aparece em sessões abertas em outro diretório. Para valer em qualquer pasta, acrescente -s user. Use um dos dois escopos, não os dois com o mesmo nome.
claude mcp add -s user --transport http flux https://flux.reportei.com/mcp/v1 \
--header "Authorization: Bearer flux_SEU_TOKEN"Para conferir o que foi gravado, sem abrir sessão:
claude mcp list # lista os servidores e o estado da conexão
claude mcp get flux # mostra a URL e os headers deste servidorclaude mcp get imprime o token
O comando mostra o header inteiro, token incluído. Evite rodá-lo com a tela compartilhada.
Cursor
Token no headerNo Cursor, o servidor é declarado no arquivo de configuração de MCP, com o token no header.
- 1Emita um token em Empresa → API e MCP.
- 2Acrescente o bloco abaixo ao seu ~/.cursor/mcp.json, trocando flux_SEU_TOKEN pelo token emitido.
- 3Reinicie o Cursor e confira na tela de MCP: o servidor flux deve aparecer com as ferramentas listadas.
{
"mcpServers": {
"flux": {
"url": "https://flux.reportei.com/mcp/v1",
"headers": { "Authorization": "Bearer flux_SEU_TOKEN" }
}
}
}n8n
Token no headerNo n8n, o Flux entra como um nó MCP Client apontando para o mesmo endereço, com o token no header. É o caminho para automações que rodam sozinhas.
- 1Emita um token em Empresa → API e MCP.
- 2Adicione um nó MCP Client e escolha o transporte HTTP.
- 3Informe a URL do servidor MCP do Flux.
- 4Configure a credencial do nó com o header abaixo.
Authorization: Bearer flux_SEU_TOKENAs ferramentas disponíveis
As de leitura cobrem os mesmos dados da API REST; as marcadas como escrita enviam mídia e criam posts, quadros e aprovações.
| Ferramenta | Responde | Escopo |
|---|---|---|
| flux_list_projects | Quais clientes existem, com fuso e idioma | projects:read |
| flux_list_posts | Posts por projeto, janela de datas, status, rede, tipo e aprovação | posts:read |
| flux_get_post | Um post inteiro: legenda, mídias, conta, agendamento e ciclo de aprovação | posts:read |
| flux_get_content_group | Todas as versões da mesma peça, uma por conta | posts:read |
| flux_list_connected_accounts | Onde um projeto publica, e a situação de cada conexão | integrations:read |
| flux_list_pinterest_boards | Os quadros de uma conta do Pinterest, lidos na hora da rede | integrations:read |
| flux_list_tiktok_privacy_options | O que uma conta do TikTok libera: privacidade, comentários, dueto e stitch | integrations:read |
| flux_review_tiktok_settings | As mensagens exatas do painel do TikTok para as escolhas feitas: avisos, consentimento e rótulo | integrations:read |
| flux_list_youtube_options | O que um Shorts do YouTube pede: privacidades e categorias da conta, e os limites de título e tags | integrations:read |
| flux_list_post_reviews | Quem aprovou, quem pediu alteração, e o que escreveu | reviews:read |
| flux_list_review_groups | Pacotes de aprovação, com resumo das decisões | reviews:read |
| flux_get_review_group | Um pacote inteiro, na ordem que o cliente vê na tela | reviews:read |
| flux_get_week_overview | O que sai numa janela: total, divisão por status, contas e dias | posts:read |
| flux_find_blocked_content | O que está parado esperando decisão, mais urgente primeiro | posts:read |
| flux_prepare_media_uploadEscrita | O comando para enviar uma imagem ou vídeo que está em arquivo local, em partes se for grande | media:write |
| flux_import_media_from_urlEscrita | Traz para o Flux uma imagem ou vídeo publicado num endereço https, baixado pelo próprio Flux | media:write |
| flux_import_media_from_chatEscrita | Traz para o Flux uma imagem ou vídeo que está na conversa, anexado ou gerado, quando o cliente entrega o arquivo à ferramenta | media:write |
| flux_get_mediaEscrita | Estado de uma mídia (ready, processing, failed), tipo e dimensões | media:write |
| flux_create_pinterest_boardEscrita | Cria um quadro novo numa conta do Pinterest | posts:create |
| flux_create_postEscrita | Cria uma peça em uma ou mais contas: rascunho, agendamento, publicação imediata ou envio para aprovação | posts:create |
| flux_update_postEscrita | Altera um post que ainda não saiu: legenda, mídias, data, envio para aprovação | posts:update |
| flux_publish_postEscrita | Publica agora posts que já existem num grupo, passando por cima da data e da aprovação | posts:update |
| flux_mark_review_statusEscrita | Define o status da revisão de posts de um grupo, com comentário opcional | reviews:create |
A lista depende dos escopos
Uma credencial só vê as ferramentas dos escopos que possui: com posts:read apenas, as de aprovação e as de escrita não aparecem na lista. Se uma ferramenta não aparece no cliente, é escopo faltando.
Como o assistente escreve
As ferramentas de escrita seguem as mesmas regras da tela, e as instruções do servidor orientam o assistente a confirmar com você antes de qualquer coisa ir ao ar.
Agendar coloca conteúdo no ar sozinho
flux_create_post com intent schedule marca a data, e na hora marcada o post é publicado sem nova confirmação. A data é sempre lida no fuso do projeto, e a resposta devolve a data com o offset, para você conferir.
Publicar agora não tem volta
flux_create_post com intent publish_now e flux_publish_post põem o post no ar em instantes, passando por cima da data e da aprovação. O assistente mostra quais posts vão sair e só publica com a sua confirmação.
Rascunho e envio para aprovação não publicam nada
São os caminhos seguros para montar a peça pelo chat e decidir depois, inclusive o pré-agendamento, em que você escolhe se o post sai na data mesmo sem aprovação.
A mídia entra por três caminhos
Arquivo da conversa, por flux_import_media_from_chat, quando o cliente entrega o arquivo à ferramenta (caso do ChatGPT); arquivo local, pelo comando que flux_prepare_media_upload devolve; ou endereço https público, por flux_import_media_from_url, que o próprio Flux baixa. Se um caminho falhar, o assistente tenta os outros e nunca cria o post sem a mídia pedida.
No Pinterest, o quadro é sempre você quem escolhe
O assistente lista os quadros com flux_list_pinterest_boards e pergunta, mesmo quando só existe um. Se nenhum servir, cria um com flux_create_pinterest_board.
No TikTok, valem as diretrizes de compartilhamento da rede
Antes de todo post, flux_list_tiktok_privacy_options relê a conta e devolve as opções, e flux_review_tiktok_settings devolve os avisos e a declaração de consentimento exatos do painel para as suas escolhas. Privacidade, comentários, dueto, stitch e divulgação comercial são perguntados, sem valor padrão, e o post só é criado com o seu consentimento expresso.
No YouTube, título, privacidade e categoria são seus
flux_list_youtube_options lê as opções da conta na hora, e o assistente pergunta cada uma antes de criar o Shorts.
Limites e comportamento das respostas
As ferramentas respondem para um modelo, não para um parser: elas cortam o que é grande e dizem como refinar a busca.
Paginação
10 itens por página por padrão, 25 no máximo. Resposta cortada vem com uma linha dizendo quantos itens existem e como refinar a busca.
response_format
concise (padrão) resume a legenda e devolve mídia sem URL; detailed traz a legenda completa e as URLs.
URLs de mídia
Expiram em 48 horas, como na API REST. Baixe o arquivo se precisar guardá-lo.
Tamanho de arquivo
Imagem e vídeo até o teto da rede social, 300 MB. Até 40 MB é um envio só; acima disso a ferramenta abre um envio em partes, que pode ser retomado. O assistente não comprime nem corta arquivo para caber.
Datas
Locais do fuso do projeto, tanto na entrada (AAAA-MM-DD) quanto na saída (ISO-8601 com o offset do projeto).
Identificadores
São devolvidos como texto, e aceitos como texto ou número.
Limite de requisições
120 requisições por minuto por credencial, o mesmo teto geral da API REST.
Alcance
A conta e os projetos autorizados na credencial. Não há parâmetro que alcance outra conta; um id fora do alcance responde como um id inexistente, de propósito.
Chamada repetida
flux_create_post e flux_publish_post não duplicam: a mesma chamada, com os mesmos argumentos e pela mesma credencial, em até 10 minutos, devolve o resultado da primeira vez, com um aviso de que nada foi criado nem publicado de novo. Não é preciso enviar chave: o servidor reconhece a chamada pelos argumentos. Se a peça foi apagada no Flux nesse intervalo, o pedido igual cria outra.
Chave de idempotência
Opcional em flux_create_post e flux_publish_post: peça ao assistente para usar uma chave (idempotency_key) e valem as regras da API REST. A mesma chave com os mesmos argumentos, em até 24 horas e em qualquer credencial da conta, devolve o resultado da primeira vez; com outros argumentos ou na outra ferramenta, é recusada com -32301, o equivalente do 422 idempotency_key_reused da API. As chaves do MCP e do header Idempotency-Key da API REST são independentes.
Códigos de erro das ferramentas
Esses erros viajam dentro de uma resposta HTTP 200, de propósito: o modelo lê a mensagem e se corrige, em vez de ver uma porta fechada.
| Código | Significado | O que fazer |
|---|---|---|
| -32300 | Limite de requisições estourado | Aguardar os segundos indicados na mensagem |
| -32301 | Valor fora do formato que o schema não pega (uma data inexistente, por exemplo) | A mensagem diz o formato correto |
| -32302 | Escopo ausente, ou id fora do alcance da credencial | A mensagem diz o próximo passo; liste antes de filtrar por id |
| -32400 | Falha inesperada no Flux | Citar o request_id da mensagem ao suporte |
| -32602 | Parâmetro fora do schema (enum inválido, número acima do máximo). Vem do SDK do protocolo, com texto em inglês | A mensagem lista os valores aceitos |
Quando algo dá errado
| Sintoma | Causa | O que fazer |
|---|---|---|
| Falha de conexão com 401 | Token ausente, inválido, expirado ou revogado | Conferir o header do cliente e emitir outro token |
| Falha de conexão com 403 | Endereço com host ou origem não reconhecidos pelo servidor | Usar exatamente o endereço desta página, sem barra no fim |
| Uma ferramenta não aparece na lista | A credencial não tem o escopo dela | Conceder o escopo que falta: nova autorização (OAuth) ou novo token |
| Conectou por OAuth, mas o assistente não cria nem agenda | A autorização concedeu só escopos de leitura | Revogar a conexão em Empresa → API e MCP e conectar de novo, marcando as permissões de escrita |
| A sessão não mostra o servidor | Sessão aberta antes do registro, ou registro no escopo local de outra pasta | Abrir sessão nova, na pasta do registro, ou registrar com -s user |
| O cliente tenta um endereço que você não configurou | O mesmo nome existe em dois escopos, com endpoints diferentes | claude mcp list avisa em MCP config diagnostics; remover o errado com claude mcp remove <nome> -s user ou -s local |
| -32301 dizendo que a chamada ainda está sendo processada | A mesma escrita chegou enquanto a primeira ainda rodava | Não repetir: conferir o resultado com flux_list_posts em alguns segundos |
Testar a conexão por fora
Para separar problema de cliente de problema de servidor, faça o handshake direto. Respondeu 200 com o header Mcp-Session-Id? O servidor está bom, e o problema é o cliente.
curl -si -X POST https://flux.reportei.com/mcp/v1 \
-H "Authorization: Bearer flux_SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'Revogar o acesso
Na mesma tela Empresa → API e MCP ficam os tokens e as conexões feitas por OAuth. O botão de revogar tem efeito imediato: a próxima requisição com aquela credencial responde 401.
Para deixar de usar o servidor no cliente, sem revogar o token:
claude mcp remove flux -s local