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 — sem escrever código.

Por baixo, as ferramentas chamam exatamente a mesma API pública v1 do Flux, com o mesmo token, os mesmos escopos e o mesmo alcance de projetos. O que muda é a forma de perguntar.

Endereço do servidor

https://flux.reportei.com/mcp/v1

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

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.

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

Escopos e o que cada um libera

Os escopos são escolhidos na tela de consentimento (OAuth) ou na emissão do token, e definem quais ferramentas o cliente enxerga.

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 Configurações → Tokens de API: /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-resource

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

1. 1Abra Configurações → Conectores e escolha adicionar um conector personalizado.
2. 2Cole a URL do servidor MCP do Flux e confirme.
3. 3O Claude abre a tela de consentimento do Reportei: entre com a sua conta, escolha qual conta (company) autorizar e quais escopos conceder.
4. 4De volta ao Claude, o conector aparece com as ferramentas do Flux. Ative-o na conversa e pergunte.

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

1. 1Abra Configurações → Conectores e escolha criar um conector.
2. 2Cole a URL do servidor MCP do Flux e escolha OAuth como forma de autenticação.
3. 3Autorize na tela do Reportei: conta e escopos.
4. 4Ative o conector na conversa para que o ChatGPT use as ferramentas do Flux.

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

1. 1Abra Configurações → Conectores e escolha adicionar um conector.
2. 2Cole a URL do servidor MCP do Flux e confirme.
3. 3Autorize na tela do Reportei: conta e escopos.
4. 4Volte ao Perplexity e confira que as ferramentas do Flux aparecem no conector.

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

1. 1Emita um token em Configurações → Tokens de API, com os escopos que você quer expor.
2. 2Registre o servidor no terminal, trocando flux_SEU_TOKEN pelo token emitido.
3. 3Abra uma sessão nova: o servidor é carregado na inicialização, então uma sessão que já estava aberta não o vê.
4. 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 — e 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 servidor

No Cursor, o servidor é declarado no arquivo de configuração de MCP, com o token no header.

1. 1Emita um token em Configurações → Tokens de API.
2. 2Acrescente o bloco abaixo ao seu ~/.cursor/mcp.json, trocando flux_SEU_TOKEN pelo token emitido.
3. 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" }
    }
  }
}

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

1. 1Emita um token em Configurações → Tokens de API.
2. 2Adicione um nó MCP Client e escolha o transporte HTTP.
3. 3Informe a URL do servidor MCP do Flux.
4. 4Configure a credencial do nó com o header abaixo.

Authorization: Bearer flux_SEU_TOKEN

As ferramentas disponíveis

Todas são somente leitura, e cobrem os mesmos dados da API REST.

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.

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.

Quando algo dá errado

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 Configurações → Tokens de API, o botão de revogar tem efeito imediato: a próxima requisição com aquele token responde 401.

Para deixar de usar o servidor no cliente, sem revogar o token:

claude mcp remove flux -s local