Fluid MCP Server
Resumo rápido: o Fluid MCP Server conecta agentes de IA (Claude, Cursor, outros clientes MCP) ao seu workspace Fluid. Com ele, dá para monitorar execuções, investigar falhas de FlowKits e reprocessar eventos direto de uma conversa, sem abrir o console. A configuração leva 3 passos: criar uma credencial do tipo mcp em Credenciais, gerar um token M2M no Playground e registrar o servidor no seu cliente MCP.
O que é MCP?
O Model Context Protocol (MCP) é um padrão aberto que permite que agentes de IA — como Claude, Cursor e ChatGPT — se conectem a ferramentas externas e executem ações em nome do usuário.
Pense nele como uma "tomada universal" entre o agente de IA e os sistemas que você já usa. Em vez de copiar e colar dados entre ferramentas, você faz uma pergunta em linguagem natural e o agente busca, analisa e age diretamente nas suas plataformas.
O que é o Fluid MCP Server?
O Fluid MCP Server é a integração da plataforma Fluid com o MCP. Com ele, você pode monitorar execuções, investigar falhas e reprocessar eventos diretamente de uma conversa com seu agente de IA — sem precisar abrir o console da Fluid.
Uma pergunta em linguagem natural substitui minutos de navegação.
Para quem é
- Operadores e times de suporte que precisam agir rápido em falhas sem depender do time técnico
- Times de Customer Success que querem visibilidade da instalação do cliente sem solicitar acesso à conta
- Gestores que querem acompanhar execuções sem abrir ferramentas técnicas
- Devs que já usam Claude, Cursor ou outros agentes e querem integrar o Fluid ao fluxo natural de trabalho
Como funciona na prática
Cenário 1 — Investigação e reprocessamento de falha
É sexta à noite. O time de operações recebe um alerta de falha. Ninguém do time técnico está disponível. O operador abre o Claude e começa:
Detecção
Operador: "Tivemos falhas hoje?"
Claude: "Sim, encontrei 2 falhas hoje:
- get-user-by-id falhou às 17:56 — disparado por evento, durou 33ms
- denis-http-error falhou às 17:40 — disparado manualmente por Denis Azevedo, durou 526ms"
Sem abrir o console. Sem filtrar nada. Uma pergunta, uma resposta.
Investigação
Operador: "O que aconteceu com o get-user-by-id das 17:56?"
Claude: "A execução 9eb1c8c1 do flow get-user-by-id falhou em 33ms — rápido demais para chegar ao processamento, o que indica falha na etapa de entrada, provavelmente validação do evento ou conector de origem. O resultado registrado foi: Execution failed."
Remediação
Operador: "Reprocessa esse evento."
Claude: "Vou reprocessar o evento associado à execução 9eb1c8c1 do flow get-user-by-id. Isso vai disparar uma nova execução com os dados originais do evento. Confirma?"
Operador: "Sim, pode reprocessar."
Claude: "Feito. Nova execução iniciada com sucesso."
Para entender os campos e status retornados nesse tipo de investigação, veja Status de execução e Análise de Problemas.
Cenário 2 — Visibilidade de instalação do cliente
Um analista de Customer Success recebe uma reclamação: a integração do cliente não está funcionando. Sem precisar de acesso ao console do cliente, o CS abre o agente:
CS: "O cliente acme tem algum FlowKit com problema?"
Claude: "Tenant acme tem 12 FlowKits ativos. Um está com status error: conector-erp v1.0.0 — ativado por Ana Marcal em 05/06, 0 flows provisionados. Os demais 11 estão com status success."
CS: "Zero flows — isso indica falha na ativação?"
Claude: "Sim. conector-erp (identificador: acme-erp-01) falhou antes de provisionar os flows — possivelmente erro de configuração de conector ou parâmetro inválido na ativação. Recomendo verificar os logs de ativação com o cliente."
Em dois turnos de conversa, o CS tem o diagnóstico completo e já sabe o que perguntar ao cliente.
Para o conceito de FlowKits e ativação, veja FlowkitsFlowkits e Ativando um FlowkitAtivando um Flowkit
O que muda com o Fluid MCP
Configuração
Pré-requisitos
- Acesso ao console da Fluid, no workspace correto
- Acesso à internet
- Um cliente MCP compatível: Claude Desktop, Claude Code, Cursor ou outro
Este guia detalha a configuração para Claude Desktop e Claude Code. Se você usa Cursor ou outro cliente MCP, o processo é o mesmo em essência — o cliente precisa apontar para a URL https://mcp.api.fluidapi.io/mcp com transporte HTTP e enviar o header Authorization: Bearer <token> — mas a forma de configurar (arquivo, comando ou tela de settings) varia de cliente para cliente. Consulte a documentação do seu cliente MCP para o formato exato.
Passo 1 — Criar as credenciais no console
- No console da Fluid, acesse Configurações → Credenciais no menu lateral.
- Confirme que está no workspace correto — as credenciais dão acesso apenas às informações desse workspace.
- Crie uma nova credencial preenchendo:
- Nome: um nome identificável (ex: mcp-integration)
- Escopo: MCP
- Validade: defina um prazo (ex: 30 dias), para não precisar gerar o token com frequência
- Salve. Você receberá um client_id e um client_secret — guarde os dois, serão usados nos próximos passos.
Veja mais detalhes sobre tipos de credencial e como gerenciá-las em Credenciais.
Passo 2 — Gerar um token de acesso no Playground
Use o Playground da Fluid para gerar o token — não é necessário rodar nenhum comando:
- Acesse a seção Credentials no menu lateral.
- Em Client Credentials, preencha o Client ID e o Client Secret gerados no Passo 1, e selecione o environment correto (ex: production, se o console também estiver em produção).
- Avance para M2M Token. O campo Scope é opcional — pode deixar em branco.
- Clique em Generate M2M Token.
- O token aparece na seção Response — copie-o. Ele será usado para autenticar o cliente MCP.
Atenção: Nunca compartilhe seu token ou suas credenciais de API.
Para conferir o conteúdo do token gerado, cole-o em jwt.io.
Passo 3 — Adicionar o servidor MCP ao Claude
Claude Code:
Confirme que o servidor foi registrado:
Você deverá ver uma entrada chamada fluid.
Para conectar:
- Abra o menu MCP no Claude (/mcp)
- Localize o servidor fluid
- Clique em Reconnect
Quando a conexão for estabelecida, o servidor aparecerá como connected e as ferramentas da Fluid estarão disponíveis.
Claude Desktop:
O Claude Desktop usa transporte stdio. Adicione o Fluid MCP Server via proxy mcp-remote:
Arquivo de configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
O token fica em texto puro nesse arquivo. Não o commite em repositório de código, nem o compartilhe por chat ou e-mail. Se o computador for compartilhado, confira as permissões de leitura do arquivo antes de salvar o token nele.
Importante: depois de editar o arquivo e salvar, feche o Claude Desktop completamente — não apenas a janela. Confira se não ficou nenhum processo minimizado ou na bandeja do sistema (Windows, macOS e Linux) antes de reabrir. Só assim a nova configuração é carregada.
Após reabrir, confirme em Configurações → Developer que o servidor fluid aparece com status running.
Teste rápido: peça ao agente, em linguagem natural, para listar os FlowKits disponíveis (ex: "Quais FlowKits estão disponíveis?") e confira se a resposta bate com o que aparece no console.
Renovação de token
Os tokens têm validade limitada. Quando expiram, as chamadas ao MCP retornam 401 Unauthorized.
Para renovar:
- Gere um novo token (Passo 2Passo 2 acima)
- Atualize a configuração do servidor MCP substituindo o token antigo
- Reconecte o servidor no menu MCP
A maioria dos clientes MCP não renova tokens automaticamente. Sempre que o token expirar, será necessário repetir esse processo.
Ferramentas disponíveis
list_executions
Lista as execuções de flows do seu workspace.
Filtros disponíveis:
Parâmetro | Descrição | Exemplo |
|---|---|---|
status | success, failed, pending, warning | failed |
flow_name | Nome do flow (busca parcial) | get-user |
flow_origin | manual, event, scheduled | event |
started_from | Data/hora de início (ISO-8601) | 2026-06-07T00:00:00-03:00 |
started_to | Data/hora de fim (ISO-8601) | 2026-06-07T23:59:59-03:00 |
tags | Lista de tags (todas devem coincidir) | ["prod", "critico"] |
page | Página (base 0) | 0 |
page_size | Itens por página (máx. 50) | 20 |
Exemplos de perguntas:
- "Liste as execuções com falha de hoje"
- "Quantas execuções rodaram essa semana via webhook?"
get_execution_status
Retorna o status detalhado de uma execução, incluindo o breakdown por steps.
Parâmetro | Descrição |
|---|---|
execution_id | ID da execução (obrigatório) |
include_steps | Incluir detalhes dos steps (padrão: true) |
Exemplos de perguntas:
- "O que aconteceu na execução 9eb1c8c1?"
- "Em qual step o flow get-user-by-id falhou?"
inspect_step
Inspeciona o request e response HTTP de um step específico de uma execução.
Exemplos de perguntas:
- "Qual foi o payload enviado para o conector no step 2?"
- "O que o sistema externo respondeu nesse step?"
list_flowkit_activations
Lista os FlowKits ativados no seu workspace, com status, versão, conectores e informações de quem realizou a ativação.
Parâmetro | Descrição | Exemplo |
|---|---|---|
status | success, error, in_progress, warning | error |
identifier | Filtrar pelo slug da ativação | acme-erp-01 |
sort_field | Campo de ordenação | audit.created.timestamp |
sort_order | ASC ou DESC (padrão: DESC) | DESC |
page / per_page | Paginação (máx. 50) | |
Exemplos de perguntas:
- "Quais FlowKits estão ativos no meu workspace?"
- "Tem algum FlowKit com status error?"
get_flowkit
Retorna os detalhes completos de um FlowKit: documentação, parâmetros de configuração e slots de conexão necessários.
Exemplos de perguntas:
- "Quais parâmetros preciso para ativar o FlowKit salesforce-sync?"
- "Quais conectores o FlowKit de ERP exige?"
list_flowkits
Lista o catálogo de FlowKits disponíveis para ativação.
Parâmetro | Descrição | Exemplo |
|---|---|---|
q | Busca por nome ou descrição | salesforce |
page / per_page | Paginação (máx. 50) | |
Exemplos de perguntas:
- "Quais FlowKits estão disponíveis para ativar?"
- "Tem algum FlowKit relacionado ao Salesforce?"
list_workspace_connections
Lista as instâncias de conector configuradas no workspace. Use antes de activate_flowkit para descobrir os IDs de instância de cada slot de conexão.
Parâmetro | Descrição | Exemplo |
|---|---|---|
connector_id | Filtrar pelo tipo de conector | abc-123 |
name | Filtrar por nome (busca parcial) | Salesforce Prod |
Exemplos de perguntas:
- "Quais conexões de Salesforce tenho disponíveis?"
activate_flowkit
Ativa um FlowKit no tenant, criando os flows a partir do template.
Operação de escrita. O agente sempre apresenta um resumo do que será feito e pede sua confirmação antes de executar. A ativação é assíncrona — acompanhe o resultado com get_flowkit_activation.
Fluxo recomendado pelo agente:
- get_flowkit → descobre parâmetros e slots de conexão
- list_workspace_connections → resolve os IDs de instância
- Confirmação do usuário
- activate_flowkit
- get_flowkit_activation → verifica o resultado
get_flowkit_activation
Retorna o status completo de uma ativação pelo seu ID. Use após activate_flowkit para acompanhar o resultado.
Exemplos de perguntas:
- "A ativação do FlowKit já terminou?"
- "O que deu errado na ativação?"
resend_event
Reprocessa um evento, disparando uma nova execução com os dados originais (ou modificados).
Operação de escrita. O agente sempre apresenta um resumo do que será feito e pede sua confirmação antes de executar.
Parâmetro | Descrição |
|---|---|
event_id | ID do evento original (obrigatório) |
data | Payload alternativo (opcional) |
headers | Headers alternativos (opcional) |
query_params | Query params alternativos (opcional) |
tags | Tags para identificar a nova execução (opcional) |
changed_event | true se o payload foi modificado (padrão: false) |
Exemplos de perguntas:
- "Reprocessa o evento da execução que falhou às 17:56"
- "Tenta de novo com o mesmo payload"
- "Reprocessa, mas muda o campo user_id para 123"
Comportamento esperado
Execuções recém-disparadas podem demorar para aparecer. Após um replay com resend_event, a execução pode levar até 1 minuto para aparecer em list_executions. A plataforma Fluid indexa execuções de forma assíncrona — aguarde alguns instantes e repita a consulta.
Segurança
- Cada requisição é isolada por workspace — você só vê dados do seu tenant
- Operações de escrita (resend_event, activate_flowkit) sempre exigem confirmação explícita antes de executar
- Suas credenciais nunca são expostas nas respostas do agente
Solução de problemas
Sintoma | Possível causa | Como resolver |
|---|---|---|
401 Unauthorized | Token expirado ou inválido | Gere um novo token e atualize a configuração |
403 Forbidden | Credencial sem permissão | Verifique as permissões da credencial |
not authenticated | Header Authorization ausente ou inválido | Confirme o formato Bearer <token> |
Servidor não aparece no cliente | Configuração incorreta | Execute claude mcp list e revise a configuração |
Não aparecem ferramentas | Servidor desconectado | Reconecte pelo menu /mcp |
Erro de SSL/timeout | Problema de conectividade | Verifique acesso à internet e regras de rede |
Suporte
Em caso de dúvidas, entre em contato com o time Fluid ou abra um ticket em suporte.fluidapi.io