MCP workflow tools now accept JSON and surface helpful error hints
When users pass JSON objects to n8n's MCP workflow tools instead of SDK code, they now get actionable guidance instead of cryptic errors.
MCP clients building workflows programmatically sometimes passed plain JSON objects to n8n's workflow validation and modification tools, triggering a cryptic error: "builder.regenerateNodeIds is not a function." This happened because the underlying SDK expected TypeScript built with the workflow() function, but received a plain object instead.
The fix enables the SDK's parseWorkflowCodeToBuilder to handle both SDK code and plain JSON workflow objects. When JSON is detected—identified by the presence of a nodes array—it gets converted to a proper WorkflowBuilder automatically. For cases where parsing genuinely fails, a new WorkflowCodeParseError class now wraps the error, and MCP tools surface this with a helpful hint directing clients to consult the SDK reference tool before retrying.
These changes live in the n8n workflow-sdk and the MCP tool layer within the CLI package, affecting validate_workflow, update_workflow, and create_workflow_from_code MCP tools.
View Original GitHub Description
Summary
- Extend
parseWorkflowCodeToBuilderto support JSON workflow objects or throw a meaningful error otherwise. - Introducing
WorkflowCodeParseErrorerror and using it's hints in MCP tool response to nudge MCP clients to use proper SDK syntax before retrying
Context: We had reports of users trying to call MCP tools that use this method by passing JSON instead of SDK code and getting cryptic errors (see attached community issue). My hunch is that this is caused by MCP clients not consulting SDK reference tool/resource and hallucinating the syntax when building workflows. This PR makes validation work with JSON objects but also, more importantly, gives hints on how to recover if parsing error is thrown.
Related Linear tickets, Github issues, and Community forum posts
Fixes ADO-5051 Fixes #28051
Review / Merge checklist
- I have seen this code, I have run this code, and I take responsibility for this code.
- PR title and summary are descriptive. (conventions) <!-- **Remember, the title automatically goes into the changelog. Use `(no-changelog)` otherwise.** -->
- Docs updated or follow-up ticket created.
- Tests included. <!-- A bug is not considered fixed, unless a test is added to prevent it from happening again. A feature is not complete without tests. -->
- PR Labeled with
Backport to Beta,Backport to Stable, orBackport to v1(if the PR is an urgent fix that needs to be backported)