Índice

Guia do Servidor MCP do n8n

Introdução e Objetivos

Este guia descreve as melhores práticas e a arquitetura para construir e manter Servidores de Processos Comuns (MCP) utilizando n8n. O objetivo é promover a modularidade, a reutilização e a manutenibilidade dos fluxos de trabalho.

Conceitos Básicos

MCP Server Trigger

O MCP Server Trigger (tipo de nó: @n8n/n8n-nodes-langchain.mcpTrigger) é um nó especializado no n8n que atua como ponto de entrada para as solicitações ao servidor MCP. Permite definir a interface de entrada e saída do servidor, e é ele que recebe as requisições externas para executar uma ou várias ferramentas.

Subfluxos (Subworkflows)

Os Subfluxos (fluxos de trabalho secundários) são fluxos de trabalho do n8n que podem ser chamados a partir de outros fluxos de trabalho. São fundamentais para a modularidade na arquitetura MCP, permitindo encapsular lógica específica em unidades reutilizáveis. Estes subfluxos implementam a lógica de uma ferramenta específica.

Nó toolWorkflow (toolWorkflow Node)

O nó toolWorkflow (tipo de nó: @n8n/n8n-nodes-langchain.toolWorkflow) é utilizado no fluxo principal do servidor MCP para chamar um subfluxo (ferramenta). Atua como uma ponte, configurando como o subfluxo é chamado e como suas entradas e saídas são mapeadas. A descrição ATDF da ferramenta é colocada neste nó.

Boas Práticas MCP

Arquitetura

Nomenclatura (Convenções de Nomes)

Saída Padrão

Validação

Segurança

Documentação

Versionamento

Princípios Chave para a Robustez de Fluxos de Trabalho

Para assegurar que os servidores MCP e suas ferramentas (subfluxos) sejam confiáveis e fáceis de depurar, devem-se seguir estes princípios fundamentais:

  1. Aderência ao Formato de Saída Padrão: Todo subfluxo (ferramenta) deve devolver consistentemente o Formato Padrão de Saída JSON, seja para sucesso (status: "success") ou erro (status: "error"), incluindo os campos data e meta apropriados.
  2. Validação Exaustiva de Entradas: Cada subfluxo deve validar rigorosamente seus parâmetros de entrada no início. Ver a seção Validação de Entradas e Erros Uniformes.
  3. Tratamento Explícito de Erros em Nós Críticos: Para nós que realizam operações suscetíveis a falhas (ex: chamadas a APIs externas com HTTP Request, interações com serviços como Google Calendar), configurar explicitamente o tratamento de erros. Isso pode ser feito usando a opção “Configurações” > “Continue On Fail” no nó, seguido de um nó IF para verificar se $json.error existe e assim dirigir o fluxo para a preparação de uma resposta de erro padrão. Alternativamente, pode-se usar a opção “Error Workflow” do nó para dirigir a falha a um fluxo de trabalho de tratamento de erros dedicado.
  4. Cobertura de Todas as Rotas Lógicas: Assegurar que todas as ramificações possíveis dentro de um fluxo de trabalho (ex: em nós IF ou Switch) terminem explicitamente num nó que gere uma saída padrão (sucesso ou erro). Evitar “caminhos mortos” onde uma ramificação não produz uma resposta formatada, o que poderia levar a erros silenciosos ou respostas inesperadas.
  5. Uso Estratégico de “Error Workflows” do n8n:
    • Nível de Nó: Para nós críticos ou complexos como @n8n/n8n-nodes-langchain.toolWorkflow, configurar um “Error Workflow” específico na aba “Configurações” do nó pode proporcionar um tratamento de falhas granular.
    • Nível de Instância (Global): Configurar um “Error Workflow” global para a instância do n8n (a partir de “Settings” / “Configurações” do n8n) serve como uma rede de segurança final para capturar e tratar quaisquer erros não controlados que possam ocorrer em qualquer fluxo de trabalho.
  6. Registro (Logging) Significativo: Implementar o registro de eventos importantes, parâmetros de entrada chave e erros em pontos críticos dos fluxos de trabalho. Utilizar o nó n8n-nodes-base.logMessage ou ferramentas de observabilidade externas. Isto é crucial para a depuração e o monitoramento. (Ver “Testes e Depuração > Interpretação de Logs”).

O cumprimento destes princípios é fundamental e é detalhado ou exemplificado em seções posteriores como Testes e Depuração e Tratamento Global de Erros no Fluxo Principal do Servidor MCP.

Arquitetura Geral

Estrutura Básica

A arquitetura MCP baseia-se num fluxo principal (o servidor MCP) que utiliza um @n8n/n8n-nodes-langchain.mcpTrigger como ponto de entrada. Este fluxo orquestra a execução de subfluxos (ferramentas) através de nós @n8n/n8n-nodes-langchain.toolWorkflow.

graph TD
    A[@n8n/n8n-nodes-langchain.mcpTrigger] --> B{Nó Switch (Roteador baseado no nome da ferramenta do Agente AI)};
    B -- nome_ferramenta_A --> C1["@n8n/n8n-nodes-langchain.toolWorkflow (configurado para SWF_Ferramenta_A)"];
    B -- nome_ferramenta_B --> C2["@n8n/n8n-nodes-langchain.toolWorkflow (configurado para SWF_Ferramenta_B)"];
    C1 --> D[Tratamento de Resposta / Preparação para Agente AI];
    C2 --> D;

O mcpTrigger recebe uma solicitação, um nó Switch (ou lógica similar) determina qual ferramenta executar, e um nó toolWorkflow específico chama o subfluxo correspondente.

Vantagens do Uso de Subfluxos

Design de Ferramentas MCP (Subfluxos)

Formato Padrão de Saída

Sucesso

O campo status será sempre "success". O campo data contém o resultado útil da ferramenta.

{
  "status": "success",
  "data": {
    "resultado_especifico": "valor",
    "outro_dado": 123
  },
  "meta": {
    "timestamp": "2023-10-27T10:30:00Z"
  }
}

(Nota: meta.timestamp pode ser gerado com `` num nó Set).

Erro

O campo status será sempre "error". O campo data contém detalhes do erro. O campo message ou text dentro de data fornece uma mensagem legível.

{
  "status": "error",
  "data": {
    "code": "CODIGO_ERRO_UNICO",
    "message": "Descrição legível do erro.",
    "text": "Descrição legível do erro (alternativa se 'text' for usado).",
    "details": {
      "field": "nome_do_campo_com_erro",
      "expected": "tipo_ou_formato_esperado",
      "solution": "Como solucionar o problema ou o que se espera."
    }
  },
  "meta": {
    "timestamp": "2023-10-27T10:35:00Z"
  }
}

(Preferir message ou text consistentemente. Se os exemplos usam text, usar text. Assegurar que os códigos de erro como CODIGO_ERRO_UNICO estejam em maiúsculas e entre crases se referenciados no texto.).

Validação de Entradas e Erros Uniformes

{
  "status": "error",
  "data": {
    "code": "VALIDATION_ERROR",
    "message": "Parâmetros de entrada inválidos.",
    "details": {
      "field": "user_id",
      "expected": "string, non-empty",
      "solution": "Fornecer um user_id válido."
    }
  },
  "meta": {
    "timestamp": "2023-10-27T10:40:00Z"
  }
}

Template Visual Base para Subfluxos (Ferramentas)

Os subfluxos que atuam como ferramentas são tipicamente iniciados por um n8n-nodes-base.executeWorkflowTrigger (gatilho de execução de fluxo de trabalho) quando são chamados desde o fluxo principal (através de um @n8n/n8n-nodes-langchain.toolWorkflow). É crucial seguir os Princípios Chave para a Robustez de Fluxos de Trabalho ao desenhar estes templates.

Exemplo: Subfluxo “SWF_Valida_Intervalo_Datas”

  1. Início (Gatilho): Nó n8n-nodes-base.executeWorkflowTrigger. Recebe parâmetros como Start (data de início) e End (data de fim) do nó toolWorkflow no fluxo principal.
  2. Validação de Entradas: Nó n8n-nodes-base.if (ex: “Validar datas”). Verifica se as datas são válidas, se Start é anterior a End, etc. (Princípio de Robustez #2).
    • Se a validação falhar, uma ramificação (FALSE) leva a um nó n8n-nodes-base.set (ex: “Erro: Datas Inválidas”) para construir o JSON de erro padrão (Princípio de Robustez #1).
  3. Lógica Principal (se a validação estiver correta): Pode incluir outros nós para processar as datas, se necessário. Neste exemplo, a própria validação é a lógica principal.
  4. Saída Bem-sucedida: Nó n8n-nodes-base.set (ex: “Sucesso: Intervalo Válido”). Prepara o JSON de resposta bem-sucedida padrão (Princípio de Robustez #1). 
    {
  "status": "success",
  "data": {
    "message": "O intervalo de datas é válido.",
    "start_date": "",
    "end_date": ""
  },
  "meta": {
    "timestamp": ""
  }
}
  5. Saída de Erro (da validação ou lógica principal): Nó n8n-nodes-base.set (ex: “Erro: Datas Inválidas”). Prepara o JSON de resposta de erro padrão (Princípio de Robustez #1). 
    {
  "status": "error",
  "data": {
    "code": "INVALID_DATE_RANGE",
    "text": "A data de início deve ser anterior à data de fim.",
    "details": {
      "field_start": "",
      "field_end": "",
      "condition": "Start < End"
    }
  },
  "meta": {
    "timestamp": ""
  }
}

    (Nota: O exemplo “Valida_Intervalo_Datas” usa data.text para a mensagem, por isso reflete-se aqui. O código de erro INVALID_DATE_RANGE está em maiúsculas.)

  6. Fim do Subfluxo: O subfluxo termina. Os dados preparados no nó Set da ramificação executada (sucesso ou erro) são devolvidos implicitamente ao fluxo chamador (ao nó toolWorkflow). Assegurar a cobertura de todas as rotas lógicas (Princípio de Robustez #4).
graph TD
    A[n8n-nodes-base.executeWorkflowTrigger <br> (Recebe: Start, End)] --> B{n8n-nodes-base.if <br> (Validar Datas: Start < End?)};
    B -- TRUE (Válido) --> S_PREP[n8n-nodes-base.set <br> (Prepara JSON Sucesso: status=success, data={message, dates}, meta)];
    S_PREP --> Z[Fim do Subfluxo <br> (Retorna JSON de S_PREP)];
    B -- FALSE (Inválido) --> E_PREP[n8n-nodes-base.set <br> (Prepara JSON Erro: status=error, data={code, text, details}, meta)];
    E_PREP --> Z;

Exemplo de Fluxo Principal (Servidor MCP)

O fluxo principal utiliza um @n8n/n8n-nodes-langchain.mcpTrigger como ponto de entrada.

  1. MCP Server Trigger: Nó @n8n/n8n-nodes-langchain.mcpTrigger. Define o endpoint, e é onde o Agente AI (Langchain) envia as solicitações para executar ferramentas.
  2. Validação de Solicitação (Opcional, delegada ao mcpTrigger): O mcpTrigger trata parte da validação da solicitação do agente.
  3. Roteador/Dispatcher (Nó Switch): Um nó n8n-nodes-base.switch dirige a execução com base no nome da ferramenta solicitada pelo agente AI (ex: ``). Cada saída do Switch conecta-se a um nó @n8n/n8n-nodes-langchain.toolWorkflow específico. (Ver “Tratamento Global de Erros no Fluxo Principal do Servidor MCP” para erros de roteamento).
  4. Chamada a Subfluxo (Ferramenta): O nó @n8n/n8n-nodes-langchain.toolWorkflow é responsável por:
    • Identificar o subfluxo a executar (configurado nos seus parâmetros).
    • Mapear as entradas para o subfluxo (ex: usando expressões como `` para obter parâmetros da solicitação do agente AI).
    • Executar o subfluxo.
    • Receber a resposta (JSON de sucesso/erro) do subfluxo. (Ver “Tratamento Global de Erros no Fluxo Principal do Servidor MCP” para falhas do toolWorkflow ou respostas inválidas).
  5. Tratamento da Resposta do Subfluxo: A saída do toolWorkflow (que é a saída do subfluxo) pode ser processada adicionalmente, se necessário, antes de ser devolvida ao mcpTrigger.
  6. Resposta ao Agente AI: O mcpTrigger encarrega-se de enviar a resposta de volta ao agente AI.

Considerações Gerais

Integração do Formato ATDF (Automatic Tool Definition Format)

Como Integrá-lo

O bloco de descrição ATDF (em formato YAML) deve ser incluído diretamente no parâmetro description do nó @n8n/n8n-nodes-langchain.toolWorkflow que chama o subfluxo correspondente. Este nó toolWorkflow atua como a representação da ferramenta dentro do servidor MCP principal e é o que o agente AI “vê”.

Campos Recomendados para ATDF

Exemplo de Bloco ATDF (YAML)

Este bloco seria colocado no campo “Description” de um nó @n8n/n8n-nodes-langchain.toolWorkflow que está configurado para chamar o subfluxo SWF_Get_User_Profile.

---
description: Obtém o perfil de um utilizador a partir do seu ID.
how_to_use:
  inputs:
    - name: user_id # Este 'name' é o que o Agente AI usará
      type: string
      required: true
      description: Identificador único do utilizador.
  outputs:
    status: string (success/error)
    data: (se status for success)
      name: string
      email: string
    data: (se status for error)
      code: string
      text: string # ou message, ser consistente
      details: object
    meta:
      timestamp: string (ISO 8601)
when_to_use: Quando é necessária informação detalhada de um utilizador específico.
---

Mini-Template ATDF Comentado (YAML)

---
# Nome descritivo da ferramenta, visível para o agente AI.
# name: tool.minha_acao.minha_entidade
# (O 'name' é geralmente tratado pelo MCP Trigger ou ToolWorkflow,
#  esta seção ATDF vai no campo 'description' desse nó)

# Descrição concisa do que a ferramenta faz.
description: Realiza uma ação específica sobre uma entidade.

# Instruções sobre como usar a ferramenta, incluindo entradas e saídas.
how_to_use:
  inputs:
    # Lista de parâmetros de entrada que a ferramenta espera.
    - name: parametro_requerido
      type: string # Tipos comuns: string, number, boolean, object, array
      required: true # true se o parâmetro for obrigatório, false se opcional.
      description: Descrição detalhada deste parâmetro e seu propósito.
                  # Incluir exemplos de valores, se útil.
    - name: parametro_opcional
      type: number
      required: false
      description: Parâmetro que não é estritamente necessário.
      default: 10 # Valor padrão se não fornecido (informativo para o ATDF).

  outputs:
    # Descrição da estrutura de saída que a ferramenta devolve.
    # Isto deve alinhar-se com o Formato Padrão de Saída do guia.
    status: string # Sempre "success" ou "error".
    data: object # Contentor para os dados da resposta.
      # Subcampos de 'data' se status for "success":
      # resultado_sucesso: string
      # outro_dado: number
      # Subcampos de 'data' se status for "error":
      # code: string
      # message: string (ou text)
      # details: object (com campos field, expected, solution)
    meta: object # Metadados da resposta.
      # timestamp: string # Data e hora em formato ISO 8601.

# Quando esta ferramenta deve ser usada. Descreve os casos de uso apropriados.
when_to_use: Ideal para quando é necessário [descrever o cenário de uso].
             Não usar se [descrever contraindicações ou alternativas].
---

Validação da Sintaxe ATDF (YAML)

O ATDF é escrito em YAML. Para assegurar que a sintaxe da sua descrição ATDF está correta antes de a colar no campo de descrição de um nó n8n, é altamente recomendável validá-la. Pode usar:

Uso de Subservidores MCP como Ferramentas

Um servidor MCP (principal) pode utilizar ferramentas expostas por outros servidores MCP (subservidores) através do nó @n8n/n8n-nodes-langchain.mcpClient.

Configuração

Vantagens

Exemplo Visual (Diagrama de Fluxo)

flowchart LR
  A[Agente MCP Principal] --> B("@n8n/n8n-nodes-langchain.mcpClient");
  B -- sseEndpoint: http://github-mcp/sse --> C[Subservidor MCP GitHub (@mcpTrigger)];
  B -- sseEndpoint: http://docs-mcp/sse --> D[Subservidor MCP Documentação (@mcpTrigger)];
  B -- sseEndpoint: http://code-mcp/sse --> E[Subservidor MCP Código (@mcpTrigger)];

O nó mcpClient (B) no Agente MCP Principal conecta-se a vários subservidores MCP (C, D, E), cada um com o seu próprio @n8n/n8n-nodes-langchain.mcpTrigger.

Considerações sobre a Descrição de Ferramentas Externas (via MCP Client)

Quando um servidor MCP principal utiliza ferramentas de um subservidor MCP através do nó @n8n/n8n-nodes-langchain.mcpClient:

Perguntas Frequentes (FAQ)

1. O que acontece se um subfluxo (ferramenta) falhar inesperadamente?

2. Pode-se ter um subfluxo que invoque outro subfluxo?

3. Como versionar corretamente os subfluxos e manter a compatibilidade?

Testes e Depuração

Esta seção foca-se em como verificar a implementação dos Princípios Chave para a Robustez de Fluxos de Trabalho e depurar problemas.

1. Testes de Subfluxos (Ferramentas) de Forma Isolada

2. Interpretação de Logs (Ver Princípio de Robustez #6 sobre a importância do logging)

3. Captura de Erros Silenciosos ou Inesperados

Guia de Exportação/Importação e Versionamento com Git

1. Exportação e Importação de Fluxos de Trabalho no n8n

2. Estratégia de Versionamento com Git

3. Organização do Repositório (Sugestões)

4. Fluxo de Trabalho Básico com Git

Uso de Etiquetas (Tags) nos Fluxos de Trabalho do n8n

1. Benefícios do Uso de Etiquetas

2. Como Usar Etiquetas no n8n

3. Estratégias de Etiquetagem Sugeridas para Servidores MCP e Ferramentas

4. Exemplos Combinados

5. Filtragem por Etiquetas

Recomendação: Defina uma convenção de etiquetagem para a sua equipa ou organização e seja consistente na sua aplicação. Um bom sistema de etiquetagem é inestimável à medida que a sua instância n8n cresce.

Tratamento Global de Erros no Fluxo Principal do Servidor MCP

Esta seção aborda como o fluxo principal do servidor MCP deve tratar falhas relacionadas com a orquestração de ferramentas, complementando os Princípios Chave para a Robustez de Fluxos de Trabalho que se aplicam a cada subfluxo.

1. Importância do Tratamento de Erros ao Nível do Servidor Principal

2. Cenários de Erro no Fluxo Principal e Como Tratá-los

a. Falha do Nó @n8n/n8n-nodes-langchain.toolWorkflow - Causa Possível: O subfluxo especificado no nó toolWorkflow não existe (ex: ID incorreto, não importado), ou há um problema crítico com a configuração do próprio nó toolWorkflow que impede que sequer tente executar o subfluxo. - Tratamento: - Aplicar o Princípio de Robustez #5: Configurar a aba “Configurações” > “Error Workflow” para o nó @n8n/n8n-nodes-langchain.toolWorkflow. Este Error Workflow dedicado pode então gerar uma resposta JSON padrão (ex: com status: "error", data.code: "TOOL_EXECUTION_FAILED", e uma mensagem apropriada). - Um “Error Workflow” global para a instância n8n (Princípio de Robustez #5) também atuaria como uma salvaguarda.

b. Subfluxo Devolve uma Resposta Estruturalmente Inválida - Causa Possível: Um subfluxo (ferramenta) termina e devolve dados, mas estes não se ajustam ao formato esperado (ex: falta o campo status, ou status não é nem "success" nem "error"). Isto indica um incumprimento do Princípio de Robustez #1 por parte do subfluxo. - Tratamento: - Após cada nó @n8n/n8n-nodes-langchain.toolWorkflow no fluxo principal (ou após um nó Switch que encaminha para vários toolWorkflows), adicionar um nó n8n-nodes-base.if para validar a estrutura da resposta. - Condições do IF: Verificar se o campo status existe e se é "success" OU "error". - Ramificação FALSE do IF (Resposta Inválida): - Conectar a um nó n8n-nodes-base.set que construa uma resposta de erro padrão. - Exemplo de JSON de erro: json { "status": "error", "data": { "code": "INVALID_TOOL_RESPONSE_STRUCTURE", "message": "A ferramenta devolveu uma resposta com uma estrutura inesperada.", "details": { "tool_name": "", "received_response_preview": "" } }, "meta": { "timestamp": "" } } - Ramificação TRUE do IF (Resposta Válida): Continuar o fluxo normalmente.

c. Erro no Roteador (ex. Nó Switch) - Causa Possível: O nome da ferramenta fornecido pelo agente AI não coincide com nenhuma das rotas definidas no nó Switch. - Tratamento: - O nó Switch no n8n tem uma saída “Default” ou “Fallback”. Conectar esta saída a um nó n8n-nodes-base.set. - Este nó Set deve gerar uma resposta de erro padrão (Princípio de Robustez #1) indicando que a ferramenta não foi encontrada. - Exemplo de JSON de erro: json { "status": "error", "data": { "code": "TOOL_NOT_FOUND", "message": "A ferramenta solicitada não está disponível ou não é reconhecida.", "details": { "requested_tool_name": "" } }, "meta": { "timestamp": "" } }

3. Considerações Adicionais

Um tratamento de erros robusto ao nível do fluxo principal do servidor MCP complementa o tratamento de erros dentro de cada subfluxo, criando um sistema mais resiliente e previsível.