FT-MCP-SERVER· 1.6.0Integrações

Conectar agentes de IA ao Lefia (servidor MCP)

O agente de IA da sua empresa (Joule, Claude, MuleSoft Agent Fabric ou outro cliente MCP) consulta integrações, mensagens, erros, números do Monitor, o relatório de negócio, o catálogo de formatos e os seus incidentes de suporte — com uma chave da empresa.

Atualizado em 28/09/2026

O Lefia tem um servidor MCP (Model Context Protocol, o padrão que os agentes de IA usam para chamar ferramentas). Com ele, o agente de IA que a sua empresa já usa pergunta ao Lefia e recebe a resposta com os dados desta empresa — por exemplo: "tem nota presa com o parceiro X?", "por que o pedido 4500123 não chegou?", "como foi o dia em produção?".

O que o agente consegue fazer

Por padrão, só ler: nenhuma ferramenta altera dados. Com a permissão Permitir ações na chave, o agente também executa as ações da seção abaixo — sempre com confirmação.

Ferramenta	Responde
`list_integrations`	Quais integrações existem e se estão entregando (falhas e entregas das últimas 24 h, última execução, última falha)
`search_messages`	Mensagens por período, situação (entregue, em espera, falhou, em trânsito), integração, documento, tipo ou parceiro
`get_message`	Uma mensagem em detalhe, com o erro explicado: resposta do destino, categoria e ação recomendada, erros de mapeamento, diagnóstico de IA (se já houver)
`monitor_summary`	Os números do Monitor no período: total, entregues, em espera, falhas, em trânsito, taxa de sucesso e latência
`list_executions`	Execuções recentes das integrações
`business_report`	O relatório de negócio do período, lido do conteúdo dos documentos: quanto foi pedido, entregue e faturado, por parceiro comercial e por material (valor e quantidade), evolução por dia. Clientes aparecem por pseudônimo; moedas diferentes nunca são somadas; quando o período é maior que o lido, a resposta diz que é amostra
`search_catalog`	Busca no catálogo de formatos (IDoc, OData, EDIFACT, X12, NF-e, UBL, JSON…) por código, nome ou descrição, incluindo os formatos que esta empresa definiu
`get_catalog_message`	Os campos de um formato como o Lefia usa para esta empresa (o formato global mais as extensões dela): tipo, tamanho, se é obrigatório de verdade, se repete, valores permitidos
`list_tickets`	Os incidentes de suporte de quem emitiu a chave — os mesmos que essa pessoa vê em Meus incidentes: código, título, categoria, urgência, situação e datas (abertos por padrão; fechados ou todos sob pedido)
`get_ticket`	Um desses incidentes com a conversa pública, em ordem, marcando o que é da empresa e o que é do suporte do Lefia. Quem escreveu, notas internas da equipe e capturas de tela não saem

O ambiente (DEV, QAS ou PRD) é escolhido a cada pergunta; o padrão é PRD. Ambiente inativo na empresa não responde.

Ações (só com permissão)

Chave emitida com Permitir ações (Configurações → Conectar agentes de IA) libera três ações. Sem a permissão, o agente nem as enxerga. A chave com ações só vale enquanto quem a emitiu for administrador ativo da empresa; se a pessoa perder o papel ou sair, a chave para de responder.

Ação	O que faz
`retry_message`	Reprocessa uma mensagem que falhou — o mesmo botão Reprocessar do Monitor. Mensagem entregue, em trânsito ou aguardando confirmação não é reprocessada (duplicaria o documento no parceiro)
`create_ticket`	Abre um incidente com o suporte do Lefia em nome de quem emitiu a chave (aparece para essa pessoa em Meus incidentes)
`comment_ticket`	Responde, como essa pessoa, um incidente dela (não vale para incidente fechado)

Toda ação tem duas etapas. Na primeira chamada nada muda: o agente recebe o plano (o que vai acontecer, com o texto exato que será gravado) e um código de confirmação que vale 10 minutos, uma vez, só para aquela chave e aqueles argumentos. O agente mostra o plano a você e só executa se você confirmar. Dados pessoais no texto do agente são mascarados antes de gravar. Proposta e execução ficam na trilha de auditoria.

Como conectar

Em Configurações → Conectar agentes de IA (MCP) (só o administrador da empresa), dê um nome à chave (ex.: "Joule — financeiro") e clique em Emitir credencial.
Copie a chave na hora — ela começa com lfm_ e não aparece de novo. O Lefia guarda só uma impressão (hash) dela.
No seu cliente MCP, cadastre o endereço do servidor mostrado na tela (termina em /api/mcp), transporte Streamable HTTP, com o cabeçalho Authorization: Bearer lfm_…. A tela traz um exemplo pronto para clientes com servidor remoto (Claude Code, Cursor, VS Code, MuleSoft MCP Bridge) e para o Claude Desktop (via mcp-remote).

Emita uma chave por agente ou ferramenta: assim você revoga uma sem derrubar as outras. A chave vence (padrão 365 dias, máximo 730) e pode ser revogada a qualquer momento na mesma tela.

Conectar por OAuth

Alguns clientes MCP não aceitam colar uma chave: pedem login. É o caso do conector personalizado do claude.ai e de outros clientes que seguem a autorização do MCP (OAuth 2.1). Para eles:

Cadastre no cliente só o endereço do servidor (termina em /api/mcp) — sem cabeçalho.
O cliente abre uma tela do Lefia no navegador. Entre com a sua conta (se ainda não estiver), escolha a empresa e confira para onde o acesso volta — o nome do aplicativo é informado por ele mesmo; o endereço de retorno é o que vale.
Clique em Autorizar. Pronto: o cliente recebe um acesso só leitura para aquela empresa, renovado sozinho enquanto estiver em uso.

Só o administrador da empresa autoriza, e a tela lista apenas as empresas que você administra. O acesso vale só para a empresa escolhida e deixa de valer se quem autorizou perder o papel de administrador ou sair da empresa. As mesmas regras da chave valem aqui: só leitura, conteúdo das mensagens nunca enviado, dados pessoais mascarados, trilha de auditoria e limite de 60 requisições por minuto.

Para desconectar, vá em Configurações → Conectar agentes de IA (MCP) → Aplicativos conectados e clique em Desconectar: o aplicativo perde o acesso na hora. A lista mostra quem autorizou, quando e o último uso.

Privacidade e segurança

A chave vale só para esta empresa e só para o servidor MCP. A credencial de export de relatórios (lfx_) não abre o MCP, e a chave MCP não abre o export.
O conteúdo das mensagens (payload) nunca é enviado ao agente. Ele recebe metadados (documento, tipo, parceiros, situação, horários) e explicações.
Textos livres (resposta do destino, mensagens de erro, diagnóstico) saem com dados pessoais mascarados (CPF, CNPJ, e-mail, telefone, IBAN, cartão). Dos erros de mapeamento sai a estrutura (campo, origem, esperado, sugestão), nunca o valor recebido.
Se a empresa desativar o uso de IA (Configurações → Uso de Inteligência Artificial), o servidor MCP recusa toda chamada até a IA ser reativada.
Toda chamada fica na trilha de auditoria da empresa: qual chave, qual ferramenta, com quais filtros, se deu certo e quantos itens voltaram.
Limite de 60 requisições por minuto por chave.

Perguntas comuns

Funciona com o conector personalizado do claude.ai? Sim, pelo login OAuth (veja "Conectar por OAuth"): cadastre só o endereço do servidor e autorize a empresa na tela do Lefia.

O agente pode reprocessar uma mensagem? Sim, se a chave foi emitida com Permitir ações e a mensagem falhou — sempre com a sua confirmação (veja "Ações"). Chave sem a permissão continua só leitura.

OAuth: ações e validade

Ações: o aplicativo pode pedir também as ações (reprocessar mensagem com falha, abrir e responder incidente). A tela de autorização mostra isso; se você autorizar, cada ação continua com a confirmação em duas etapas. Quando o aplicativo pede as ações, a tela mostra a caixa Permitir ações, desmarcada: autorize sem marcar para dar só a leitura, ou marque para dar leitura e ações. Sem esse pedido, a caixa não aparece e o acesso é só leitura.
Validade: a autorização vale por até 90 dias, mesmo em uso. Depois disso o aplicativo pede uma nova autorização.
Aplicativos conectados: em Configurações → Conectar agentes de IA (MCP), cada aplicativo mostra Vence em (a data em que a autorização acaba) e Ações (Sim ou Não). Uma autorização vencida aparece como Vencida: o aplicativo precisa pedir uma nova, e você pode desconectá-lo.

Histórico de versões

1.6.0
Conexão por login (OAuth) do servidor MCP: quando o aplicativo pede as ações, a tela de autorização mostra a caixa "Permitir ações", desmarcada — autorizar sem marcar dá só a leitura. Em Configurações → Aplicativos conectados, cada aplicativo mostra quando a autorização vence (90 dias) e se ele pode agir, com o aviso de vencida; no celular a lista vira cartões.
26/09/2026 · updated
1.5.0
Conexão por login (OAuth) do servidor MCP: o aplicativo pode pedir também as ações (reprocessar mensagem com falha, abrir e responder chamado), que a tela de autorização mostra ao administrador — sempre com a confirmação em duas etapas, como na chave com "Permitir ações". Sem pedido, o acesso segue só leitura. E a autorização passa a valer por até 90 dias: depois disso o aplicativo pede uma nova autorização, mesmo em uso contínuo.
25/09/2026 · updated
1.4.0
MCP v2, fatia 4 (última): ações com confirmação no servidor /api/mcp (versão 1.4.0). Permissão nova mcp:actions na chave MCP ("Permitir ações" na emissão; constraint report_export_tokens_scopes_check e TENANT_TOKEN_EXTRA_SCOPES). Sem ela o servidor nem registra as ações. retry_message = o Reprocessar do Monitor (reprocessMessage, agora função única da tela e do MCP) só para mensagem em falha pelo desfecho único; create_ticket abre chamado em nome da pessoa dona da chave (user_id = report_export_tokens.created_by, metadata.origin = mcp; aparece para ela em Chamados) e avisa o suporte como a tela (announceTicketCreated, extraído da rota); comment_ticket responde, como essa pessoa, um chamado dela que não está fechado. Chave sem autor não abre nem responde. Toda ação em duas etapas: plano no cliente só leitura + código lfa_ de uso único, 10 min, preso a empresa, credencial, ferramenta e hash dos argumentos (mcp_action_confirmations, só hash, só service_role); chave com ações só vale enquanto quem a emitiu for administrador ativo da empresa (conferido a cada chamada; senão 403 e mcp_key.owner_not_admin na trilha); execução consome o código de forma atômica, depois do limite por credencial (10/min; 3/min para abrir chamado). Texto do agente gravado redigido; trilha mcp.action_proposed / mcp.action_executed (sensível) com argumentos redigidos e sem o código.
25/09/2026 · updated
1.3.0
MCP v2, fatia 3: OAuth 2.1 no servidor /api/mcp (versão 1.3.0), atrás da flag MCP_OAUTH_ENABLED (nasce desligada). O Lefia é o próprio servidor de autorização: descoberta RFC 9728 (/.well-known/oauth-protected-resource[/api/mcp], anunciada no WWW-Authenticate do 401) e RFC 8414 (/.well-known/oauth-authorization-server); registro dinâmico RFC 7591 só de cliente público (redirect https ou loopback http, nome como texto não confiável, limite por IP); tela /mcp/authorize com login e volta, escolha da empresa entre as que a pessoa administra, cliente, endereço de retorno e escopo; código de uso único (5 min) com PKCE S256 obrigatório, state e resource (RFC 8707) conferidos; access token opaco lfo_ (1 h) e refresh lfr_ (30 d) com rotação — reuso de código ou de refresh derruba a concessão inteira; revogação RFC 7009. Só o SHA-256 de código e tokens vai para o banco (mcp_oauth_clients/grants/codes/tokens, só service_role). /api/mcp aceita a chave lfm_ ou o access token → o mesmo McpCaller (agora com scopes e via), empresa sempre da concessão, que só vale enquanto quem autorizou é administrador ativo; limite por credencial, consentimento de IA e trilha mcp.tool_called mantidos. Configurações → MCP lista os aplicativos conectados (quem autorizou, quando, último uso) e desconecta. Trilha: mcp_oauth.authorized, denied, revoked e reuse_detected. Único escopo: mcp:read.
25/09/2026 · updated
1.2.0
MCP v2, fatia 2: chamados no servidor /api/mcp (versão 1.2.0). list_tickets = chamados de suporte da pessoa que emitiu a chave (report_export_tokens.created_by), na empresa da chave — o mesmo recorte da tela Chamados, em que quem não é interno vê só os próprios; chave sem autor não vê nada. Abertos por padrão (open, in_progress, waiting_user), fechados ou todos, busca por código (igualdade) ou trecho do título (sem curinga), paginado. get_ticket = um desses chamados por código ou id com descrição, resolução e a conversa pública em ordem, cada mensagem marcada pelo papel real de quem escreveu (lefia_support = super_admin/support; company = o resto). Não saem: quem abriu ou respondeu, comentários internos (is_internal), captura de tela, navegador, contexto técnico e metadados; chamado de colega ou da vizinha responde igual a inexistente. Texto livre pelo redator do agente. Cliente só leitura e trilha mcp.tool_called, como as demais.
25/09/2026 · updated
1.1.0
MCP v2, fatia 1: três ferramentas de leitura novas no servidor /api/mcp (versão 1.1.0). business_report = a tela Relatórios → Negócio lida por um agente: mesmo período das telas (resolveReportPeriod, 7/30/90 dias ou dias personalizados), mesmos números (buildBusinessReport + loadBusinessIntelligence: totais, evolução por dia, parceiros comerciais, materiais por valor e quantidade, pedido/entrega/fatura, clientes por pseudônimo), lado origem ou destino, amostra marcada (sampled) quando a camada semântica cortou, moedas diferentes nunca somadas, texto livre redigido. search_catalog e get_catalog_message = catálogo de formatos (loadCatalogSummary, findEffectiveFormat): base global mais formatos próprios e extensões SÓ da empresa da chave; campos com tipo, tamanho, obrigatório absoluto, repetição e valores permitidos, paginados. Todas rodam no cliente só leitura e ficam na trilha mcp.tool_called.
25/09/2026 · updated