--- title: Fluid MCP Server slug: fluid-mcp-server docTags: createdAt: 2026-06-29T17:46:11.537Z --- :::hint{type="info"} **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." :::hint{type="info"} 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. :::hint{type="info"} Para o conceito de FlowKits e ativação, veja [Flowkits](docId\:teosUy9T7cjEQUPLrBuxj) e [Ativando um Flowkit](docId\:ro-H12S_MvQRgbRxjdVt0) ::: ## 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 :::hint{type="info"} 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 ` — 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 1. No console da Fluid, acesse **Configurações → Credenciais** no menu lateral. 2. Confirme que está no workspace correto — as credenciais dão acesso apenas às informações desse workspace. 3. 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 4. 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](docId\:FQqCGO6xtw5a5ygCCdq8v). ### Passo 2 — Gerar um token de acesso no Playground Use o [Playground da Fluid](https://playground.fluidapi.io/) para gerar o token — não é necessário rodar nenhum comando: 1. Acesse a seção **Credentials** no menu lateral. 2. 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). 3. Avance para **M2M Token**. O campo **Scope** é opcional — pode deixar em branco. 4. Clique em **Generate M2M Token**. 5. O token aparece na seção **Response** — copie-o. Ele será usado para autenticar o cliente MCP. :::hint{type="warning"} **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:** :::BlockQuote claude mcp add --transport http fluid https\://mcp.api.fluidapi.io/mcp \\ \--header "Authorization: Bearer COLE_SEU_TOKEN_AQUI" ::: Confirme que o servidor foi registrado: :::BlockQuote claude mcp list ::: Você deverá ver uma entrada chamada `fluid`. Para conectar: 1. Abra o menu MCP no Claude (`/mcp`) 2. Localize o servidor `fluid` 3. 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`: :::BlockQuote \{ "mcpServers": \{ "fluid": \{ "command": "npx", "args": \[ "mcp-remote", "https\://mcp.api.fluidapi.io/mcp", "--header", "Authorization: Bearer SEU\_TOKEN" ] } } } ::: 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` :::hint{type="warning"} 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. ::: :::hint{type="info"} **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: 1. Gere um novo token ([Passo 2](docId\:rjSm5xhdvbCvBlVIAH1LY) acima) 2. Atualize a configuração do servidor MCP substituindo o token antigo 3. Reconecte o servidor no menu MCP :::hint{type="info"} 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: 1. `get_flowkit` → descobre parâmetros e slots de conexão 2. `list_workspace_connections` → resolve os IDs de instância 3. Confirmação do usuário 4. `activate_flowkit` 5. `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 \ | | 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](https://suporte.fluidapi.io)