System Tools

Utilities for health checks and self-documentation. The tools_documentation tool is how your AI learns to use all n8n-mcp capabilities.

How AI Self-Discovery Works

Your AI assistant uses tools_documentation to learn about all available tools, their parameters, and best practices. This means you don't need to explain tool syntax — just describe what you want to accomplish.

`n8n_health_check`

Check n8n instance health and API connectivity. Performs comprehensive health check of your n8n instance through its API.

n8n API Key Required

Parameter	Type	Default	Description
`mode`	`string`	`status`	Check mode `statusdiagnostic`
`verbose`	`boolean`	`false`	Extra details in diagnostic mode

Quick health check

javascript

n8n_health_check({})

Detailed diagnostics

javascript

n8n_health_check({mode: "diagnostic", verbose: true})

Use Cases

•Pre-flight checks before deployments
•Continuous monitoring of n8n instance
•Troubleshooting connectivity issues
•Verifying API compatibility

✓Best Practices

•Run health check before deploying workflows
•Use diagnostic mode for troubleshooting
•Check regularly as part of monitoring

`tools_documentation`

The meta-documentation tool that your AI uses to learn how to use all n8n-mcp tools. Returns documentation for any MCP tool, including itself. This is how your AI discovers tool capabilities on its own.

No Setup Required

Parameter	Type	Default	Description
`topic`	`string`	—	Tool name, special topic (javascript_code_node_guide, python_code_node_guide, ai_agents_guide), or "overview"
`depth`	`string`	`essentials`	Documentation depth `essentialsfull`

Get overview of all tools

javascript

tools_documentation()

Learn about a specific tool

javascript

tools_documentation({topic: "search_nodes"})

Get comprehensive details

javascript

tools_documentation({topic: "validate_workflow", depth: "full"})

Code node guides

javascript

tools_documentation({topic: "javascript_code_node_guide"})

AI Agents guide

javascript

tools_documentation({topic: "ai_agents_guide", depth: "full"})

Use Cases

•Learning about available tools
•Getting usage examples for specific tools
•Accessing code node guides
•Understanding AI Agent patterns

✓Best Practices

•Start with overview to understand available tools
•Use depth="full" for comprehensive documentation
•Check guides for code node patterns

`n8n_instances`

Switch which of your n8n instances the current MCP session targets. Only visible to the agent when you've enabled multi-instance mode in the dashboard. Lets the AI work against several n8n instances (prod, staging, client A, client B…) within a single session without you having to reconfigure the MCP client.

No Setup Required

Parameter	Type	Default	Description
`mode`*	`string`	—	list returns the available instances; switch changes the session's current selection. `listswitch`
`name`	`string`	—	Required when mode='switch'. Case-insensitive match against an instance name (the friendly handle you set in the dashboard).

See what's available

javascript

n8n_instances({mode: "list"})

Returns all active instances on your account, marks which one is default and which is currently selected for this session.

Switch by name

javascript

n8n_instances({mode: "switch", name: "staging"})

Subsequent tool calls in this MCP session now target the staging instance. Other concurrent MCP sessions are not affected — each session has its own current instance.

Natural language prompt

javascript

// In Claude / Cursor / ChatGPT
"List my n8n workflows on staging, then deploy this one to prod."

Your AI picks the right switch calls automatically — no need to invoke the tool yourself.

Use Cases

•Operating multiple n8n environments (dev/staging/prod) from a single AI session
•Agencies managing several client instances from one Claude/Cursor session
•Running parallel agents — each on a different instance (each gets its own session, so selections don't collide)
•Quickly comparing the same workflow's execution across instances

✓Best Practices

•Enable multi-instance mode in the dashboard FIRST (Instances page → toggle). The tool stays hidden until then.
•Give your instances memorable names (prod, staging, client-acme) — the agent will use them in prompts and reports.
•Mark one instance as your default — every new MCP session starts on it.
•Trust the agent: 'deploy to prod' typically routes through switch + tool calls in one turn.

Common Pitfalls

•Switching only affects the current MCP session. If you open a second session (e.g., a new Claude Code conversation), it starts fresh on the default until you switch.
•Switching to an instance that's been deleted from the dashboard falls back to the default with a warning — the agent's next list call will show the updated set.
•Reserved names (default, current, list, switch) can't be used as instance names — the dashboard validator catches this.

`n8n_audit_instance`

Security audit for your n8n instance. Combines n8n's built-in audit (credentials, database, nodes, instance, filesystem) with a custom deep scan across all workflows for hardcoded secrets, unauthenticated webhooks, missing error handling, and risky data retention. Returns a markdown report with a remediation playbook.

n8n API Key Required

Parameter	Type	Default	Description
`categories`	`array`	—	Subset of built-in audit categories to run `credentialsdatabasenodesinstancefilesystem`
`includeCustomScan`	`boolean`	`true`	Run the custom deep scan in addition to built-in checks
`customChecks`	`array`	—	Subset of custom deep-scan checks `hardcoded_secretsunauthenticated_webhookserror_handlingdata_retention`
`daysAbandonedWorkflow`	`number`	—	Days threshold for flagging a workflow as abandoned

Full audit (default)

javascript

n8n_audit_instance()

Runs both built-in checks and the custom deep scan

Only built-in audit, specific categories

javascript

n8n_audit_instance({
  categories: ["credentials", "nodes"],
  includeCustomScan: false
})

Only secret/webhook deep scan

javascript

n8n_audit_instance({
  customChecks: ["hardcoded_secrets", "unauthenticated_webhooks"]
})

Use Cases

•Pre-production security review
•Periodic compliance scans
•Finding hardcoded API keys, tokens, and PII inside workflow nodes
•Identifying webhooks exposed to the internet without authentication

✓Best Practices

•Run before going to production and on a schedule afterwards
•Triage by severity — work the critical/high findings first
•Use the remediation playbook's three sections: auto-fixable, requires review, requires user action
•Detected secrets are masked (first 6 + last 4 chars) — rotate them, don't try to read them out of the report

Common Pitfalls

•Custom scan walks every workflow — slower on large instances (capped at 5,000 workflows)
•Archived workflows are excluded by n8n
•PII detection uses pattern matching and produces false positives — review before acting