Índice

Guía del Servidor MCP de n8n

Introducción y objetivos

Esta guía describe las mejores prácticas y la arquitectura para construir y mantener Servidores de Procesos Comunes (MCP) utilizando n8n. El objetivo es promover la modularidad, la reutilización y la mantenibilidad de los flujos de trabajo.

Conceptos básicos

MCP Server Trigger

El MCP Server Trigger (tipo de nodo: @n8n/n8n-nodes-langchain.mcpTrigger) es un nodo especializado en n8n que actúa como punto de entrada para las solicitudes al servidor MCP. Permite definir la interfaz de entrada y salida del servidor, y es el que recibe las peticiones externas para ejecutar una o varias herramientas.

Subworkflows

Los Subworkflows (flujos de trabajo secundarios) son flujos de trabajo de n8n que se pueden llamar desde otros flujos de trabajo. Son fundamentales para la modularidad en la arquitectura MCP, permitiendo encapsular lógica específica en unidades reutilizables. Estos subworkflows implementan la lógica de una herramienta específica.

toolWorkflow Node

El nodo toolWorkflow (tipo de nodo: @n8n/n8n-nodes-langchain.toolWorkflow) es utilizado en el flujo principal del servidor MCP para llamar a un subworkflow (herramienta). Actúa como un puente, configurando cómo se llama al subworkflow y cómo se mapean sus entradas y salidas. La descripción ATDF de la herramienta se coloca en este nodo.

Buenas prácticas MCP

Arquitectura

Naming (Convenciones de Nombres)

Salida estándar

Validación

Seguridad

Documentación

Versionado

Principios Clave para la Robustez de Flujos de Trabajo

Para asegurar que los servidores MCP y sus herramientas (subworkflows) sean confiables y fáciles de depurar, se deben seguir estos principios fundamentales:

  1. Adherencia al Formato de Salida Estándar: Todo subworkflow (herramienta) debe devolver consistentemente el Formato Estándar de Salida JSON, ya sea para éxito (status: "success") o error (status: "error"), incluyendo los campos data y meta apropiados.
  2. Validación Exhaustiva de Entradas: Cada subworkflow debe validar rigurosamente sus parámetros de entrada al inicio. Ver la sección Validación de Entradas y Errores Uniformes.
  3. Manejo Explícito de Errores en Nodos Críticos: Para nodos que realizan operaciones susceptibles a fallos (ej., llamadas a API externas con HTTP Request, interacciones con servicios como Google Calendar), configurar explícitamente el manejo de errores. Esto se puede hacer usando la opción “Configuración” > “Continue On Fail” en el nodo, seguido de un nodo IF para verificar si $json.error existe y así dirigir el flujo a la preparación de una respuesta de error estándar. Alternativamente, se puede usar la opción “Error Workflow” del nodo para dirigir el fallo a un flujo de trabajo de manejo de errores dedicado.
  4. Cobertura de Todas las Rutas Lógicas: Asegurar que todas las ramas posibles dentro de un flujo de trabajo (ej., en nodos IF o Switch) terminen explícitamente en un nodo que genere una salida estándar (éxito o error). Evitar “caminos muertos” donde una rama no produce una respuesta formateada, lo que podría llevar a errores silenciosos o respuestas inesperadas.
  5. Uso Estratégico de “Error Workflows” de n8n:
    • Nivel de Nodo: Para nodos críticos o complejos como @n8n/n8n-nodes-langchain.toolWorkflow, configurar un “Error Workflow” específico en la pestaña “Configuración” del nodo puede proporcionar un manejo de fallos granular.
    • Nivel de Instancia (Global): Configurar un “Error Workflow” global para la instancia de n8n (desde “Settings” / “Configuración” de n8n) sirve como una red de seguridad final para capturar y manejar cualquier error no controlado que pueda ocurrir en cualquier flujo de trabajo.
  6. Registro (Logging) Significativo: Implementar el registro de eventos importantes, parámetros de entrada clave y errores en puntos críticos de los flujos de trabajo. Utilizar el nodo n8n-nodes-base.logMessage o herramientas de observabilidad externas. Esto es crucial para la depuración y el monitoreo. (Ver “Pruebas y Depuración > Interpretación de Logs”).

El cumplimiento de estos principios es fundamental y se detalla o ejemplifica en secciones posteriores como Pruebas y Depuración y Manejo de Errores Globales en el Flujo Principal del Servidor MCP.

Arquitectura General

Estructura Básica

La arquitectura MCP se basa en un flujo principal (el servidor MCP) que utiliza un @n8n/n8n-nodes-langchain.mcpTrigger como punto de entrada. Este flujo orquesta la ejecución de subworkflows (herramientas) a través de nodos @n8n/n8n-nodes-langchain.toolWorkflow.

graph TD
    A[@n8n/n8n-nodes-langchain.mcpTrigger] --> B{Nodo Switch (Enrutador basado en nombre de herramienta del Agente AI)};
    B -- tool_A_name --> C1["@n8n/n8n-nodes-langchain.toolWorkflow (configurado para SWF_Tool_A)"];
    B -- tool_B_name --> C2["@n8n/n8n-nodes-langchain.toolWorkflow (configurado para SWF_Tool_B)"];
    C1 --> D[Manejo de Respuesta / Preparación para Agente AI];
    C2 --> D;

El mcpTrigger recibe una solicitud, un nodo Switch (o lógica similar) determina qué herramienta ejecutar, y un nodo toolWorkflow específico llama al subworkflow correspondiente.

Ventajas del Uso de Subworkflows

Diseño de Herramientas MCP (Subworkflows)

Formato Estándar de Salida

Éxito

El campo status siempre será "success". El campo data contiene el resultado útil de la herramienta.

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

(Nota: meta.timestamp se puede generar con `` en un nodo Set).

Error

El campo status siempre será "error". El campo data contiene detalles del error. El campo message o text dentro de data proporciona un mensaje legible.

{
  "status": "error",
  "data": {
    "code": "CODIGO_ERROR_UNICO",
    "message": "Descripción legible del error.",
    "text": "Descripción legible del error (alternativa si se usa 'text').",
    "details": {
      "field": "nombre_del_campo_con_error",
      "expected": "tipo_o_formato_esperado",
      "solution": "Cómo solucionar el problema o qué se espera."
    }
  },
  "meta": {
    "timestamp": "2023-10-27T10:35:00Z"
  }
}

(Preferir message o text consistentemente. Si los ejemplos usan text, usar text. Asegurar que los códigos de error como CODIGO_ERROR_UNICO estén en mayúsculas y entre acentos graves si se referencian en texto.).

Validación de Entradas y Errores Uniformes

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

Plantilla Base Visual para Subworkflows (Herramientas)

Los subworkflows que actúan como herramientas son típicamente iniciados por un n8n-nodes-base.executeWorkflowTrigger (activador de ejecución de flujo de trabajo) cuando son llamados desde el flujo principal (a través de un @n8n/n8n-nodes-langchain.toolWorkflow). Es crucial seguir los Principios Clave para la Robustez de Flujos de Trabajo al diseñar estas plantillas.

Ejemplo: Subworkflow “SWF_Valida_Rango_Fechas”

  1. Inicio (Activador): Nodo n8n-nodes-base.executeWorkflowTrigger. Recibe parámetros como Start (fecha inicio) y End (fecha fin) desde el nodo toolWorkflow en el flujo principal.
  2. Validación de Entradas: Nodo n8n-nodes-base.if (ej. “Validar fechas”). Verifica si las fechas son válidas, si Start es anterior a End, etc. (Principio de Robustez #2).
    • Si la validación falla, una rama (FALSE) lleva a un nodo n8n-nodes-base.set (ej. “Error: Fechas Inválidas”) para construir el JSON de error estándar (Principio de Robustez #1).
  3. Lógica Principal (si la validación es correcta): Puede incluir otros nodos para procesar las fechas si es necesario. En este ejemplo, la validación en sí misma es la lógica principal.
  4. Salida Exitosa: Nodo n8n-nodes-base.set (ej. “Success: Rango Válido”). Prepara el JSON de respuesta exitosa estándar (Principio de Robustez #1). 
    {
  "status": "success",
  "data": {
    "message": "El rango de fechas es válido.",
    "start_date": "",
    "end_date": ""
  },
  "meta": {
    "timestamp": ""
  }
}
  5. Salida de Error (desde validación o lógica principal): Nodo n8n-nodes-base.set (ej. “Error: Fechas Inválidas”). Prepara el JSON de respuesta de error estándar (Principio de Robustez #1). 
    {
  "status": "error",
  "data": {
    "code": "INVALID_DATE_RANGE",
    "text": "La fecha de inicio debe ser anterior a la fecha de fin.",
    "details": {
      "field_start": "",
      "field_end": "",
      "condition": "Start < End"
    }
  },
  "meta": {
    "timestamp": ""
  }
}

    (Nota: El ejemplo “Valida rango de fechas” usa data.text para el mensaje, así que se refleja aquí. El código de error INVALID_DATE_RANGE está en mayúsculas.)

  6. Fin del Subworkflow: El subworkflow termina. Los datos preparados en el nodo Set de la rama ejecutada (éxito o error) son devueltos implícitamente al flujo llamador (al nodo toolWorkflow). Asegurar cobertura de todas las rutas lógicas (Principio de Robustez #4).
graph TD
    A[n8n-nodes-base.executeWorkflowTrigger <br> (Recibe: Start, End)] --> B{n8n-nodes-base.if <br> (Validar Fechas: Start < End?)};
    B -- TRUE (Válido) --> S_PREP[n8n-nodes-base.set <br> (Prepara JSON Éxito: status=success, data={message, dates}, meta)];
    S_PREP --> Z[Fin del Subworkflow <br> (Retorna JSON de S_PREP)];
    B -- FALSE (Inválido) --> E_PREP[n8n-nodes-base.set <br> (Prepara JSON Error: status=error, data={code, text, details}, meta)];
    E_PREP --> Z;

Ejemplo de Flujo Principal (Servidor MCP)

El flujo principal utiliza un @n8n/n8n-nodes-langchain.mcpTrigger como punto de entrada.

  1. MCP Server Trigger: Nodo @n8n/n8n-nodes-langchain.mcpTrigger. Define el endpoint, y es donde el Agente AI (Langchain) envía las solicitudes para ejecutar herramientas.
  2. Validación de Solicitud (Opcional, delegada a mcpTrigger): El mcpTrigger maneja parte de la validación de la solicitud del agente.
  3. Router/Dispatcher (Nodo Switch): Un nodo n8n-nodes-base.switch dirige la ejecución basado en el nombre de la herramienta solicitada por el agente AI (ej. ``). Cada salida del Switch conecta a un nodo @n8n/n8n-nodes-langchain.toolWorkflow específico. (Ver “Manejo de Errores Globales” para errores de enrutamiento).
  4. Llamada a Subworkflow (Herramienta): El nodo @n8n/n8n-nodes-langchain.toolWorkflow es responsable de:
    • Identificar el subworkflow a ejecutar (configurado en sus parámetros).
    • Mapear las entradas para el subworkflow (ej. usando expresiones como `` para tomar parámetros de la solicitud del agente AI).
    • Ejecutar el subworkflow.
    • Recibir la respuesta (JSON de éxito/error) del subworkflow. (Ver “Manejo de Errores Globales” para fallos del toolWorkflow o respuestas inválidas).
  5. Manejo de Respuesta del Subworkflow: La salida del toolWorkflow (que es la salida del subworkflow) puede ser procesada adicionalmente si es necesario antes de ser devuelta al mcpTrigger.
  6. Respuesta al Agente AI: El mcpTrigger se encarga de enviar la respuesta de vuelta al agente AI.

Consideraciones Generales

Integración del Formato ATDF (Automatic Tool Definition Format)

Cómo Integrarlo

El bloque de descripción ATDF (en formato YAML) debe incluirse directamente en el parámetro description del nodo @n8n/n8n-nodes-langchain.toolWorkflow que llama al subworkflow correspondiente. Este nodo toolWorkflow actúa como la representación de la herramienta dentro del servidor MCP principal y es lo que el agente AI “ve”.

Campos Recomendados para ATDF

Ejemplo de Bloque ATDF (YAML)

Este bloque se colocaría en el campo “Description” de un nodo @n8n/n8n-nodes-langchain.toolWorkflow que está configurado para llamar al subworkflow SWF_Get_User_Profile.

---
description: Obtiene el perfil de un usuario a partir de su ID.
how_to_use:
  inputs:
    - name: user_id # Este 'name' es el que el Agente AI usará
      type: string
      required: true
      description: Identificador único del usuario.
  outputs:
    status: string (success/error)
    data: (si status es success)
      name: string
      email: string
    data: (si status es error)
      code: string
      text: string # o message, ser consistente
      details: object
    meta:
      timestamp: string (ISO 8601)
when_to_use: Cuando se requiere información detallada de un usuario específico.
---

Mini-Plantilla ATDF Comentada (YAML)

---
# Nombre descriptivo de la herramienta, visible para el agente AI.
# name: tool.mi_accion.mi_entidad
# (El 'name' suele ser manejado por el MCP Trigger o ToolWorkflow,
#  esta sección ATDF va en el campo 'description' de ese nodo)

# Descripción concisa de lo que hace la herramienta.
description: Realiza una acción específica sobre una entidad.

# Instrucciones sobre cómo usar la herramienta, incluyendo entradas y salidas.
how_to_use:
  inputs:
    # Lista de parámetros de entrada que la herramienta espera.
    - name: parametro_requerido
      type: string # Tipos comunes: string, number, boolean, object, array
      required: true # true si el parámetro es obligatorio, false si es opcional.
      description: Descripción detallada de este parámetro y su propósito.
                  # Incluir ejemplos de valores si es útil.
    - name: parametro_opcional
      type: number
      required: false
      description: Parámetro que no es estrictamente necesario.
      default: 10 # Valor por defecto si no se provee (informativo para el ATDF).

  outputs:
    # Descripción de la estructura de salida que la herramienta devuelve.
    # Esto debe alinearse con el Formato Estándar de Salida de la guía.
    status: string # Siempre "success" o "error".
    data: object # Contenedor para los datos de la respuesta.
      # Sub-campos de 'data' si status es "success":
      # resultado_exito: string
      # otro_dato: number
      # Sub-campos de 'data' si status es "error":
      # code: string
      # message: string (o text)
      # details: object (con campos field, expected, solution)
    meta: object # Metadatos de la respuesta.
      # timestamp: string # Fecha y hora en formato ISO 8601.

# Cuándo se debe usar esta herramienta. Describe los casos de uso apropiados.
when_to_use: Ideal para cuando se necesita [describir el escenario de uso].
             No usar si [describir contraindicaciones o alternativas].
---

Validación de la Sintaxis ATDF (YAML)

El ATDF se escribe en YAML. Para asegurar que la sintaxis de tu descripción ATDF es correcta antes de pegarla en el campo de descripción de un nodo n8n, es muy recomendable validarla. Puedes usar:

Uso de Subservidores MCP como Herramientas

Un servidor MCP (principal) puede utilizar herramientas expuestas por otros servidores MCP (subservidores) mediante el nodo @n8n/n8n-nodes-langchain.mcpClient.

Configuración

Ventajas

Ejemplo Visual (Diagrama de Flujo)

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 Documentación (@mcpTrigger)];
  B -- sseEndpoint: http://code-mcp/sse --> E[Subservidor MCP Código (@mcpTrigger)];

El nodo mcpClient (B) en el Agente MCP Principal se conecta a varios subservidores MCP (C, D, E), cada uno con su propio @n8n/n8n-nodes-langchain.mcpTrigger.

Consideraciones sobre la Descripción de Herramientas Externas (vía MCP Client)

Cuando un servidor MCP principal utiliza herramientas de un subservidor MCP a través del nodo @n8n/n8n-nodes-langchain.mcpClient:

Preguntas Frecuentes (FAQ)

1. ¿Qué pasa si un subworkflow (herramienta) falla inesperadamente?

2. ¿Se puede tener un subworkflow que invoque a otro subworkflow?

3. ¿Cómo versionar correctamente los subworkflows y mantener compatibilidad?

Pruebas y Depuración

Esta sección se enfoca en cómo verificar la implementación de los Principios Clave para la Robustez de Flujos de Trabajo y depurar problemas.

1. Pruebas de Subworkflows (Herramientas) de Forma Aislada

2. Interpretación de Logs (Ver Principio de Robustez #6 sobre la importancia del logging)

3. Captura de Errores Silenciosos o Inesperados

Guía de Exportación/Importación y Versionado con Git

1. Exportación e Importación de Workflows en n8n

2. Estrategia de Versionado con Git

3. Organización del Repositorio (Sugerencias)

4. Flujo de Trabajo Básico con Git

Uso de Etiquetas (Tags) en los Workflows de n8n

1. Beneficios del Uso de Etiquetas

2. Cómo Usar Etiquetas en n8n

3. Estrategias de Etiquetado Sugeridas para Servidores MCP y Herramientas

4. Ejemplos Combinados

5. Filtrado por Etiquetas

Recomendación: Define una convención de etiquetado para tu equipo u organización y sé consistente en su aplicación. Un buen sistema de etiquetado es invaluable a medida que tu instancia de n8n crece.

Manejo de Errores Globales en el Flujo Principal del Servidor MCP

Esta sección aborda cómo el flujo principal del servidor MCP debe manejar fallos relacionados con la orquestación de herramientas, complementando los Principios Clave para la Robustez de Flujos de Trabajo que se aplican a cada subworkflow.

1. Importancia del Manejo de Errores a Nivel del Servidor Principal

2. Escenarios de Error en el Flujo Principal y Cómo Manejarlos

a. Fallo del Nodo @n8n/n8n-nodes-langchain.toolWorkflow - Causa Posible: El subworkflow especificado en el nodo toolWorkflow no existe (ej. ID incorrecto, no importado), o hay un problema crítico con la configuración del propio nodo toolWorkflow. - Manejo: - Aplicar el Principio de Robustez #5: Configurar la pestaña “Configuración” > “Error Workflow” para el nodo @n8n/n8n-nodes-langchain.toolWorkflow. Este Error Workflow dedicado debe generar una respuesta JSON estándar (ej. con status: "error", data.code: "TOOL_EXECUTION_FAILED", y un mensaje apropiado). - Un “Error Workflow” global para la instancia de n8n (Principio de Robustez #5) también actuaría como un seguro.

b. Subworkflow Devuelve una Respuesta Estructuralmente Inválida - Causa Posible: Un subworkflow (herramienta) termina y devuelve datos, pero estos no se ajustan al formato esperado (ej. falta el campo status, o status no es ni "success" ni "error"). Esto indica un incumplimiento del Principio de Robustez #1 por parte del subworkflow. - Manejo: - Después de cada nodo @n8n/n8n-nodes-langchain.toolWorkflow (o después de un nodo Switch que enruta a varios toolWorkflows), añadir un nodo n8n-nodes-base.if para validar la estructura de la respuesta. - Condiciones del IF: Verificar si el campo status existe y si es "success" o "error". - Rama FALSE del IF (Respuesta Inválida): - Conectar a un nodo n8n-nodes-base.set que construya una respuesta de error estándar. - Ejemplo de JSON de error: json { "status": "error", "data": { "code": "INVALID_TOOL_RESPONSE_STRUCTURE", "message": "La herramienta devolvió una respuesta con una estructura inesperada.", "details": { "tool_name": "", "received_response_preview": "" } }, "meta": { "timestamp": "" } } - Rama TRUE del IF (Respuesta Válida): Continuar el flujo normalmente.

c. Error en el Router (ej. Nodo Switch) - Causa Posible: El nombre de la herramienta proporcionado por el agente AI no coincide con ninguna de las rutas definidas en el nodo Switch. - Manejo: - El nodo Switch en n8n tiene una salida “Default” o “Fallback”. Conectar esta salida a un nodo n8n-nodes-base.set. - Este nodo Set debe generar una respuesta de error estándar (Principio de Robustez #1) indicando que la herramienta no fue encontrada. - Ejemplo de JSON de error: json { "status": "error", "data": { "code": "TOOL_NOT_FOUND", "message": "La herramienta solicitada no está disponible o no es reconocida.", "details": { "requested_tool_name": "" } }, "meta": { "timestamp": "" } }

3. Consideraciones Adicionales

Un manejo de errores robusto a nivel del flujo principal del servidor MCP complementa el manejo de errores dentro de cada subworkflow, creando un sistema más resiliente y predecible.