El MCP de n8n para armar y validar flujos

El lienzo de n8n es genial hasta que lo armas una docena de veces y empiezas a perder más tiempo rebuscando en el panel de nodos que describiendo lo que de verdad quieres. El servidor MCP de n8n le pasa ese trabajo tedioso al modelo: le entrega a Claude el catálogo de nodos, el schema de cada uno y tools para armar un flujo, validarlo contra tu instancia y parchearlo sin re-subirlo entero. El modelo cablea los nodos; tú lees el diagrama y bajas la palanca de activación tú mismo. Aquí va el set de tools, una config real, el auth y el mínimo privilegio que necesitas, una llamada de ejemplo y los fallos que de verdad te van a morder.

01 · Qué expone el servidor

El servidor MCP de n8n conecta a Claude con tu instancia de n8n por el Model Context Protocol, y se parte limpio en dos capas. Saber en cuál estás parado te dice si una llamada es lectura inofensiva o un cambio real a tu instancia.

La capa de documentación (solo lectura, segura)

Estas tools nunca tocan tu instancia. Son la forma en que el modelo aprende tus nodos antes de proponer nada:

• search_nodes busca en el catálogo de nodos por palabra clave. El modelo la usa para dar con el nodo correcto en vez de adivinar un tipo de nodo que ni existe.
• get_node lee el schema completo de un nodo: sus parámetros, sus tipos, los campos obligatorios y las opciones de operación. Esto es lo que evita que el modelo se invente un parámetro que no está.
• search_templates y get_template encuentran y leen templates de flujos de la comunidad. Sirven como punto de partida, pero toma cualquier template como un borrador para revisar, no como un plano para confiar a ciegas.
• tools_documentation es la documentación del propio servidor, para que el modelo confirme cómo se comporta una tool en lugar de asumirlo.

La capa de gestión (escribe en tu instancia)

Estas cambian estado real, así que son las que tienes que controlar:

• n8n_create_workflow crea un flujo nuevo a partir de un grafo de nodos. Es el camino principal para armar el borrador.
• n8n_validate_workflow revisa un flujo contra el schema: credenciales que faltan, expresiones mal escritas, conexiones sueltas, tipos que no calzan. Esta es la tool que justifica toda la integración.
• n8n_update_partial_workflow aplica un diff a un flujo existente. Prefiérela sobre el update completo; edita solo la parte que cambió en vez de sobrescribir todo.
• n8n_update_full_workflow reemplaza el flujo entero. Útil pero peligrosa: una llamada mala aplasta tus ediciones a mano.
• n8n_get_workflow, n8n_list_workflows leen lo que ya existe, para que el modelo construya sobre tu instancia en vez de pelearse con ella.
• n8n_test_workflow y n8n_executions corren un flujo y leen su historial de ejecuciones, el bucle de feedback para responder "¿esto de verdad funcionó?".
• n8n_health_check confirma que la instancia responde y que la API key sirve antes de cualquier otra cosa.

02 · Setup: API key, config, URL de la instancia

Necesitas dos cosas: la URL de tu instancia de n8n y una API key de n8n. Genera la key desde Settings → API en la interfaz de n8n. Trátala como acceso total a la instancia: quien la tenga puede leer, crear y correr todos tus flujos y cada referencia a credenciales que tengas.

La decisión más importante del setup es a qué instancia pertenece la key. Genérala primero en una instancia que no sea de producción. Mientras el modelo aprende tus nodos y tú aprendes cómo arma los flujos, te conviene que una respuesta equivocada y bien segura caiga en un sandbox, no en el flujo que te hace sonar el teléfono.

Esta es la config que uso en un proyecto de Claude Code. La key vive en una variable de entorno, nunca inline:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp@latest"],
      "env": {
        "N8N_API_URL": "https://n8n.tu-sandbox.example",
        "N8N_API_KEY": "tu_api_key_de_n8n_aqui"
      }
    }
  }
}

Aquí hay dos hábitos que cargan con casi todo el peso:

1. Apunta N8N_API_URL a un sandbox mientras aprendes. Las tools de la capa de gestión escriben en la instancia que indiques aquí. Toma confianza en una instancia desechable antes de apuntarla a la que corre automatizaciones reales.
2. Mantén N8N_API_KEY en una variable de entorno o en un gestor de secretos. Nunca la pongas inline en un archivo que vayas a subir al repo, y confirma que el archivo esté en el gitignore antes del primer commit. Es la misma lección que enseña el resto del stack: los secretos viven en un store, no en el código.

03 · Mínimo privilegio: dónde vive el riesgo de verdad

Casi toda la seguridad aquí no pasa por un flag, sino por la disciplina con las credenciales. Lo peligroso no es que el modelo cree un flujo; es que un secreto termine donde no debe.

n8n tiene un store de credenciales: las API keys, los tokens de OAuth y las contraseñas de bases de datos viven ahí, cifradas, y los nodos las referencian por nombre. La idea es justamente esa: que el secreto nunca aparezca en la definición del flujo. El fallo es dejar que el modelo pegue una API key directo en un parámetro de nodo, por ejemplo un header de Authorization escrito como valor literal. Esa key queda en texto plano dentro del JSON del flujo, y ese JSON se exporta, se versiona y se comparte como cualquier otro.

La regla, sin excepción:

• Las credenciales van en el store de credenciales, referenciadas por nombre. El modelo puede conectar un nodo para que use una credencial nombrada; lo que nunca debería hacer es escribir el secreto él mismo.
• Acota la API key de n8n hasta donde tu instancia te lo permita. Si puedes emitir una key con menos alcance, hazlo, y no le des a la key de experimentación el mismo radio de daño que a la de producción.
• Trata el JSON exportado del flujo como si fuera público. Antes de subir al repo o compartir un flujo que armó el modelo, hazle grep en busca de cualquier cosa que parezca un token. Una definición de flujo debería poder pegarse en un ticket sin riesgo.

04 · El bucle de construcción: valida antes de activar

Este es el orden que sigo, y la única pieza que no puedes saltarte es validar antes de activar.

1. search_nodes / get_node deja que el modelo encuentre los nodos correctos y lea sus schemas, así cablea parámetros reales y no unos que solo se ven plausibles.
2. n8n_create_workflow arma el grafo de nodos en un flujo borrador. Inactivo. Existe, pero no corre.
3. n8n_validate_workflow revisa el borrador contra el schema. Esto atrapa lo que se ve bien en el diagrama y falla en runtime: un nodo que referencia una credencial que no existe, una expresión con un typo, una conexión cableada a la entrada equivocada.
4. n8n_test_workflow lo corre una vez, a propósito, en el sandbox, y lees la ejecución. Un flujo que valida igual puede hacer lo que no debe; una corrida real te dice lo que el schema no puede.
5. Lo activas a mano, después de haber leído el diagrama y la ejecución de prueba. Activar es una decisión humana, no la última llamada de tool del modelo.

// El orden que corro con el modelo, en palabras simples:
// 1. search_nodes / get_node      -> aprender los schemas reales de los nodos
// 2. n8n_create_workflow          -> armar un borrador INACTIVO
// 3. n8n_validate_workflow        -> atrapar creds / expresiones / enlaces malos
// 4. n8n_test_workflow            -> una corrida a propósito en el sandbox
// 5. activar a mano               -> una persona lee el diagrama y luego lo prende
//
// Ediciones después: n8n_update_partial_workflow (diff), luego re-validar.

Por qué "valida y después activa a mano" no es negociable: un flujo de n8n con un trigger de webhook o de schedule puede dispararse en el instante en que queda activo. Si activar es el paso final del modelo, el flujo puede correr antes de que hayas leído lo que hace, y "corrió antes de que yo lo revisara" es justo el resultado que todo el bucle existe para evitar. Deja la última acción del modelo en validar o probar. La palanca se queda en tu mano.

05 · Una llamada de ejemplo, de punta a punta

Digamos que lo que quieres lograr es esto: cuando entra una fila a una tabla de Supabase, llamar a Claude para que la resuma y luego publicar el resumen en Slack. No quieres colocar a mano el trigger, el nodo HTTP y el nodo de Slack, ni cablearlos uno por uno. Así que describes el resultado y dejas correr el bucle.

El modelo:

1. Corre search_nodes para "supabase trigger", "http request" y "slack", y luego get_node en cada uno para leer los parámetros reales.
2. Llama n8n_create_workflow con un grafo de tres nodos: el trigger de Supabase alimentando un nodo HTTP Request (apuntado a la API de Claude, usando una credencial del store, no una key pegada) que a su vez alimenta un nodo de Slack.
3. Llama n8n_validate_workflow. Supongamos que vuelve avisando que el nodo de Slack referencia una credencial que no existe en esta instancia.
4. Creas la credencial de Slack en el store de n8n, el modelo vuelve a validar, y ahora sí queda limpio.
5. n8n_test_workflow lo corre una vez contra una fila de prueba. Lees la ejecución: el resumen se publicó en el canal correcto.
6. Abres el flujo, lees el diagrama y lo activas tú mismo.

El trabajo que el modelo te ahorró es real: encontrar tres nodos, leer sus schemas y cablearlos bien. El trabajo que no te quitó también es real: la credencial vive en el store, tú leíste el resultado de la validación y tú bajaste el switch de activación. Esa división es justamente el punto.

06 · Fallos que sí te vas a encontrar

Ninguno de estos es exótico. Todos aparecen apenas empiezas a usar el servidor en serio.

1. Un flujo que corre antes de que lo leas. Activar fue el último paso del modelo, el trigger disparó y se ejecutó un flujo a medio revisar. Deja la última acción del modelo en validar o probar; activa tú a mano.
2. Un secreto pegado en un parámetro de nodo. El modelo escribió una API key como valor literal de un header, y ahora está en el JSON del flujo. Atrápalo en la revisión, muévelo al store de credenciales y vuelve a validar.
3. Un update completo que aplastó ediciones a mano. n8n_update_full_workflow reemplazó un flujo que habías ajustado en el lienzo. Prefiere n8n_update_partial_workflow, y guarda un export que sepas que está bueno para que un aplastón sea un restore y no un rearmado desde cero.
4. Una validación limpia que igual hace lo que no debe. La validación revisa la estructura, no la intención: confirma que la expresión parsea, no que sea la expresión que tenías en mente. Una corrida de n8n_test_workflow en el sandbox atrapa lo que el schema no puede.
5. Un modelo que se inventa un nodo o un parámetro. Te saltas get_node y el modelo adivina un tipo de nodo o un campo que no existe; la llamada de create falla o, peor, valida contra una suposición vieja. Haz que el modelo lea el schema primero.
6. La instancia equivocada. N8N_API_URL apuntaba a producción mientras experimentabas. Déjala fija en un sandbox hasta que el bucle te aburra, y recién ahí gradúala a propósito.

Vale la pena montar este servidor cuando construyes automatizaciones lo bastante seguido como para que "el modelo encuentra los nodos, arma el grafo, la validación atrapa lo obvio, tú revisas y activas" le gane a colocar cada nodo a mano. Es exagerado para un solo flujo estable que tocas dos veces al año: a ese ritmo el lienzo es más rápido que montar un bucle manejado por un modelo. Bien usado, tiene la forma correcta de un plugin: una división clara entre lectura segura y escrituras reales, los secretos guardados en el store de credenciales y un flujo que enruta cada cambio por la validación, con la palanca de activación firme en tu mano.