n8n + human approval + MCP
O assistente consulta dados por MCP, prepara uma alteração e pede revisão antes de executar. Durante a espera, o usuário precisa saber o que será feito, o sistema precisa conservar a proposta e a equipe precisa localizar a execução quando algo falha. Esta semana integra as três fronteiras estudadas: conexão externa, aprovação humana e observabilidade. O caso será uma reserva fictícia de estoque, com consulta remota e gate antes do efeito.
Vamos distinguir a confirmação da resposta do agente da aprovação de uma tool concreta. Também separaremos histórico de execução de traces de infraestrutura, incluindo as limitações da feature OpenTelemetry documentada pelo n8n. O exemplo local registra proposta, decisão e efeito com correlação, mas não usa n8n, MCP ou collector real. O laboratório completa a integração na versão instalada e conserva essa distinção nas evidências.
JavaScriptn8nMCPAvaliaçãoAutomaçãoAo terminar esta aula
- Human review precisa apresentar a tool e seus argumentos concretos.
- Compatibilidade MCP depende da instalação, do binding e da revisão.
- Observabilidade ajuda a investigar, mas não substitui autorização e idempotência.
Antes de continuar: Laboratório: Agents no n8n
MCP conectado não significa catálogo irrestrito
MCPO MCP Client Tool permite usar ferramentas de um servidor externo em um agente n8n. Configure endpoint, credencial e seleção de ferramentas conforme a instalação. A documentação atual apresenta um campo SSE Endpoint, portanto não presuma que o node implementa nativamente todos os contratos da revisão MCP2026-07-28 ou Streamable HTTP. Verifique a compatibilidade do cliente e do servidor e registre o transporte real. Uma conexão bem-sucedida comprova aquela combinação, não suporte universal. Se precisar de outro binding, escolha um adaptador compatível e teste-o.
Selecione ferramentas específicas em vez de liberar automaticamente tudo que o servidor publicar. Uma consulta de estoque pode ser oferecida sem uma operação de exclusão ou exportação. O servidor continua aplicando autorização; o host limita o catálogo que o agente pode propor. Se uma tool mudar schema ou aparecer depois, revise a seleção e a política de efeito. Descrições e anotações do servidor são informações externas, não garantias de privilégio. O executor da reserva deve reconhecer identidade, recurso e operação de maneira independente da decisão textual do agente.
Human review aprova uma chamada concreta
FundamentosA documentação do n8n descreve revisão humana ligada às tools do AI Agent. Quando uma tool exige revisão, o workflow pausa e apresenta nome e parâmetros; aprovação libera a execução e recusa cancela a chamada. Esse mecanismo é diferente de perguntar no chat se o usuário gostou da resposta. Para reservar, o humano precisa ver item, quantidade, organização e consequência. Um botão continuar sem argumentos relevantes não permite avaliar a operação. A identidade do revisor e a política de acesso também precisam ser apropriadas ao domínio.
A mensagem de revisão pode usar os campos documentados da tool para mostrar o que o agente propôs. Confira o nome e os parâmetros efetivamente apresentados, principalmente quando foram preenchidos por expressões de IA. Aprovar a proposta não deve permitir alterações posteriores invisíveis. Defina expiração, recusa e ausência de resposta de acordo com a aplicação. O silêncio não libera efeito. O mecanismo do editor precisa ser acompanhado de validação no executor, pois autorização e regra de negócio continuam existindo mesmo depois do aceite humano.
Retomada precisa preservar identidade e efeito
FundamentosDurante a espera, conserve proposta, identidade da execução e decisão. Ao retomar, verifique que a decisão se refere à proposta atual e use chave estável para reconhecer operação repetida. O simulador recebe OP7, revisão1 e quantidade1; executar exige aprovação da mesma revisão e ainda valida expiração. A recusa termina sem efeito, a decisão vencida bloqueia e duas retomadas da mesma operação recuperam um único resultado. Isso permite observar o que cada controle protege sem realizar uma reserva comercial.
Uma queda depois da reserva e antes da confirmação cria resultado desconhecido. O workflow deve consultar a operação pela chave antes de repetir. Persistir a pausa não garante idempotência do serviço MCP. A integração precisa de um executor ou armazenamento que suporte a identidade estável e a concorrência real. O mapa local da aula demonstra apenas reconhecimento dentro do processo. Documente esse limite e teste reinício e múltiplos workers quando os componentes reais oferecerem suporte; não prometa execução exatamente uma vez com base na aparência do canvas.
const efeitos=new Map(),eventos=[];
function snapshot(p){
if(!p||typeof p.id!=='string'||typeof p.sku!=='string'||typeof p.tenant!=='string'||typeof p.ator!=='string'||!Number.isInteger(p.quantidade)||p.quantidade<1||!Number.isInteger(p.revisao))throw new Error('proposta invalida');
return JSON.stringify([p.id,p.sku,p.quantidade,p.tenant,p.ator,p.revisao]);
}
function executar(p,d,agora){
const chave=snapshot(p);
if(!d||d.snapshot!==chave||d.exp<=agora)throw new Error('decisao invalida ou expirada');
eventos.push({correlacao:p.id,evento:'decisao',aprovado:d.aprovado});
if(!d.aprovado)return {status:'recusado'};
if(!efeitos.has(chave))efeitos.set(chave,{recibo:p.id+':'+p.revisao,status:'reserva_simulada'});
eventos.push({correlacao:p.id,evento:'resultado'});return efeitos.get(chave);
}
const p={id:'OP7',revisao:1,sku:'I2',quantidade:1,tenant:'lojaA',ator:'ana'};
const d={snapshot:snapshot(p),exp:200,aprovado:true};
// Todas as mutacoes devem falhar antes de qualquer efeito.
for(const mutacao of [{quantidade:999},{sku:'I99'},{id:'OP9'},{tenant:'lojaB'},{ator:'bia'}]){
try{executar({...p,...mutacao},d,100);}catch(e){console.log('bloqueio',e.message);}
if(efeitos.size!==0)throw new Error('efeito indevido');
}
console.log(executar(p,d,100),executar(p,d,100));
console.log(executar(p,{...d,aprovado:false},100));
try{executar(p,d,300);}catch(e){console.log(e.message);}
console.log({quantidadeEfeitos:efeitos.size,eventos});Histórico, traces e métricas mostram perspectivas distintas
FundamentosO histórico de execução n8n permite inspecionar dados e status dos nodes conforme retenção e configuração. Traces mostram duração e relação entre etapas e serviços quando instrumentados. Métricas agregam contagens e distribuições, como falhas, espera de aprovação e latência. Nenhuma dessas superfícies substitui o registro de autorização e o ledger de efeito. Um workflow verde não prova que a reserva foi autorizada ou emitida só uma vez. Use correlação para ligar execução, proposta, decisão, tool e resultado, mantendo dados sensíveis protegidos.
A documentação conferida informa OpenTelemetry tracing em Preview desde n8n2.19.0, configuração por interface desde2.27.0 e suporte OTLP gRPC desde2.39.0. A feature pode mudar e a fonte orienta evitar dependência de produção. Para o laboratório, use uma versão compatível e collector de desenvolvimento, ou apresente somente histórico se tracing não estiver disponível. Não afirme métricas OpenTelemetry automaticamente: a documentação distingue tracing de métricas planejadas. Confirme spans e propagação observados, e controle sampling, atributos e acesso para não enviar segredos ao collector.
Exercício aplicado
Um agente consulta estoque por MCP e propõe reservar I2. A tool de reserva exige revisão humana. A mesma operação poderá ser retomada duas vezes, e uma decisão expirada deve bloquear antes do efeito.
- Execute recusa, aprovação, expiração e repetição locais.
- Conecte MCP compatível e selecione somente consulta/reserva fictícias.
- Configure human review com nome e parâmetros visíveis.
- Capture histórico, contagem de efeitos e traces de desenvolvimento quando disponíveis.
Abrir resolução comentada
A decisão guarda um snapshot normalizado de id, item, quantidade, organização, ator e revisão. O executor calcula o mesmo snapshot e exige igualdade antes de consultar ou criar o efeito. Os casos que alteram cada campo começam com ledger vazio e devem conservar zero entradas; isso impede reutilizar aprovação de OP7 para OP9 ou outra quantidade. O snapshot deve ser registrado por backend confiável, não aceito como decisão produzida pelo modelo.
O registro local associa OP7 à proposta, à decisão e ao efeito. A recusa encerra antes do ledger, a decisão expirada falha e a retomada repetida conserva um único efeito. Os eventos mostram a posição do controle e permitem correlacionar uma tentativa ao resultado já existente. Essa é a semântica que a integração deve preservar.
No n8n, conecte as tools permitidas ao caminho de revisão e teste aprovação e recusa reais no canal de desenvolvimento. Inspecione nome e parâmetros apresentados. Histórico e tracing, quando disponível na versão escolhida, acrescentam evidências de execução, mas a prova de efeito único vem do serviço ou ledger idempotente.
const efeitos=new Map(),eventos=[];
function snapshot(p){
if(!p||typeof p.id!=='string'||typeof p.sku!=='string'||typeof p.tenant!=='string'||typeof p.ator!=='string'||!Number.isInteger(p.quantidade)||p.quantidade<1||!Number.isInteger(p.revisao))throw new Error('proposta invalida');
return JSON.stringify([p.id,p.sku,p.quantidade,p.tenant,p.ator,p.revisao]);
}
function executar(p,d,agora){
const chave=snapshot(p);
if(!d||d.snapshot!==chave||d.exp<=agora)throw new Error('decisao invalida ou expirada');
eventos.push({correlacao:p.id,evento:'decisao',aprovado:d.aprovado});
if(!d.aprovado)return {status:'recusado'};
if(!efeitos.has(chave))efeitos.set(chave,{recibo:p.id+':'+p.revisao,status:'reserva_simulada'});
eventos.push({correlacao:p.id,evento:'resultado'});return efeitos.get(chave);
}
const p={id:'OP7',revisao:1,sku:'I2',quantidade:1,tenant:'lojaA',ator:'ana'};
const d={snapshot:snapshot(p),exp:200,aprovado:true};
// Todas as mutacoes devem falhar antes de qualquer efeito.
for(const mutacao of [{quantidade:999},{sku:'I99'},{id:'OP9'},{tenant:'lojaB'},{ator:'bia'}]){
try{executar({...p,...mutacao},d,100);}catch(e){console.log('bloqueio',e.message);}
if(efeitos.size!==0)throw new Error('efeito indevido');
}
console.log(executar(p,d,100),executar(p,d,100));
console.log(executar(p,{...d,aprovado:false},100));
try{executar(p,d,300);}catch(e){console.log(e.message);}
console.log({quantidadeEfeitos:efeitos.size,eventos});Como conferir seu resultado
- Recusa e expiração geram zero efeitos.
- Repetição conserva um único recibo.
- Cada efeito possui decisão e proposta correlacionadas.
- Alterar id, sku, quantidade, tenant ou ator com a mesma decisão gera zero efeitos.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Vincular snapshot ao humano/contexto.
- Distinguir revisão, validade e ledger.
Aprovação R8 item I4 quantidade 2 atorana expira 100. Em 101 muda quantidade 3 e há retry. Decida.
Conferir raciocínio e critérios de domínio
Quantidade e ator fazem parte do snapshot; proposta alterada não usa aprovação.
Em 101 a decisão está expirada antes de consultar/criar efeito.
Replay legítimo dentro da validade mantém recibo; retomar não garante unicidade externa por si.
Evidências para autoavaliação ou revisão por pares
- Aprovação: Quantidade e ator fazem parte do snapshot; proposta alterada não usa aprovação.
- Retomada: Em 101 a decisão está expirada antes de consultar/criar efeito.
- Efeito: Replay legítimo dentro da validade mantém recibo; retomar não garante unicidade externa por si.
Um erro frequente
Aprovação genérica permite qualquer quantidade.
Aprovação vincula argumentos, ator, escopo, revisão e validade.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Aprovar a resposta do agente é aprovar qualquer tool?
Não. A revisão deve estar ligada à chamada concreta.
Nome e argumentos precisam ser apresentados antes do efeito.
2. MCP Client Tool garante suporte à revisão atual?
Não por si só. É necessário verificar cliente, servidor e transporte.
O campo e o binding suportados dependem da instalação.
3. Trace prova efeito único?
Não. Consulte o registro do executor ou serviço externo.
A observabilidade mostra execução; idempotência precisa de um contrato de efeito.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- MCP Client Tool
n8n • consulta: 2026-10-06
n8nMCPConsumir tools externas, autenticação e seleção das ferramentas expostas ao agente.
Limites: Página ainda usa SSE Endpoint; verificar versão do node e transportes realmente suportados, sem generalizar para MCP atual.
- Transports overview — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPJSON-RPC, stdio e Streamable HTTP; regras para transportes customizados.
Limites: HTTP+SSE legado não deve ser ensinado como o transporte remoto atual; streaming é opção do binding.
- Human-in-the-loop for tools
n8n • consulta: 2026-10-06
n8nPausar tool call, exibir nome/argumentos, aprovar/negar e continuar.
Limites: Canal de aprovação requer credenciais; testar negação e vínculo entre parâmetros aprovados e executados.
- View all executions
n8n • consulta: 2026-10-06
n8nInspecionar runs, estado, histórico e retentativas.
Limites: Disponibilidade de dados depende de configurações de salvamento e edição/licença.
- Trace executions with OpenTelemetry
n8n • consulta: 2026-10-06
n8nSpans de workflow/nodes, coletor OTEL e atributos de trace.
Limites: Alguns recursos exigem self-hosted Enterprise; não prometer acesso gratuito a todos os modos de observabilidade.