Fluid MCP Server
30 min
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 " 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 o que muda com o fluid mcp antes com fluid mcp abrir console, navegar, filtrar uma pergunta em linguagem natural copiar ids, acionar time técnico investigação e reprocessamento autônomos minutos de contexto para entender resposta imediata e contextualizada só quem conhece a plataforma opera qualquer pessoa da equipe opera configuração pré requisitos credenciais de api da fluid (client id e client secret) acesso à internet curl instalado jq instalado (opcional, mas recomendado) um cliente mcp compatível claude desktop, claude code, cursor ou outro passo 1 — gerar um token de acesso use suas credenciais para gerar um token oauth2 curl s 'https //id dev api fluidapi io/oauth2/token fluid legacy' \\ x post \\ h 'content type application/x www form urlencoded' \\ \ data raw 'grant type=client credentials\&client id=seu client id\&client secret=seu client secret' \\ \| jq r ' access token' o comando retorna um token jwt guarde o — ele será usado para autenticar o cliente mcp atenção nunca compartilhe seu token ou suas credenciais de api passo 2 — validar o acesso (opcional) antes de configurar o cliente mcp, confirme que o token e a conectividade estão funcionando curl i x post https //mcp dev api fluidapi io/mcp \\ h "content type application/json" \\ h "accept application/json, text/event stream" \\ h "authorization bearer seu token" \\ d '{"jsonrpc" "2 0","id" 1,"method" "initialize","params" {"protocolversion" "2025 11 25","capabilities" {},"clientinfo" {"name" "curl","version" "1 0"}}}' \\ \ max time 10 se tudo estiver correto, a resposta terá status 200 ok e o header mcp session id passo 3 — adicionar o servidor mcp ao claude code claude mcp add transport http fluid https //mcp dev api fluidapi io/mcp \\ \ header "authorization bearer cole seu token aqui" confirme que o servidor foi registrado claude mcp list você deverá ver uma entrada chamada fluid passo 4 — 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 via proxy mcp remote { "mcpservers" { "fluid" { "command" "npx", "args" \[ "mcp remote", "https //mcp dev api fluidapi io/mcp", " header", "authorization bearer seu token" ] } } } arquivo de configuração /library/application support/claude/claude desktop config json (macos) ou %appdata%\claude\claude desktop config json (windows) 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 1 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