Attach this document at the start of any AI session where you are building VH3 AI n8n workflows. It covers the node’s resources, operations, routing decisions, patterns, and constraints, and works with Claude.ai, Claude Code, Cursor, or any chat session with the file attached.
The recommended setup: official n8n connector + this document
The official n8n connector (developed by n8n GmbH, available in the Claude connector directory) connects Claude to your live n8n instance. On instances running n8n v2.18.4 or higher, it exposes the full instance-level MCP — including workflow building, not just execution.What it can do (verified on VH3-managed instances):
Tool
Purpose
get_sdk_reference
Load the n8n Workflow SDK before writing code
get_suggested_nodes
Recommended node types for a workflow pattern
search_nodes / get_node_types
Discover nodes and fetch exact parameter schemas
list_credentials
Find available credentials by name (secrets redacted)
validate_workflow
Pre-deploy validation of workflow code
create_workflow_from_code
Compile SDK code and save to your instance
search_workflows / execute_workflow
Find and run existing workflows
Setup (Claude.ai) — step by step:
1
Open Claude Code in Code mode
Switch to Code mode in Claude.ai. Your active connectors appear in the input bar at the bottom of the screen.
Claude Code with an active n8n connector shown in the input bar.
2
Open Connectors → Browse connectors
Click on the Connectors area, then click Add → Browse connectors to open the connector directory.
The Connectors panel with the Add dropdown showing Browse connectors and Add custom connector options.
3
Search for n8n in the directory
In the Directory, select Connectors and search for n8n. The official n8n connector by n8n GmbH will appear.
The Claude connector directory filtered to n8n — the official connector developed by n8n GmbH.
4
In n8n, open Settings → Instance-level MCP
Switch to your n8n instance. Click Settings in the left sidebar and select Instance-level MCP from the menu.
n8n Settings menu — Instance-level MCP is at the bottom of the list.
5
Enable MCP and copy the Server URL
Toggle Instance-level MCP on, then copy the Server URL shown in the Connection details panel. This is the URL you’ll paste back into Claude.
n8n Instance-level MCP — enabled, with the Server URL ready to copy.
VH3-managed instances: Your URL is https://{your-company}.n8n.vh3.ai/mcp-server/http. Contact VH3 support if Instance-level MCP is not yet enabled on your instance.
6
Paste the Server URL and connect
Back in the Claude connector directory, click the n8n connector. When the Install n8n dialog appears, paste your Server URL into the field and click Continue.
7
Allow OAuth access
Claude will ask for permission to access your n8n instance. Click Allow — this grants Claude the ability to list, execute, create, and update workflows on your behalf.
The OAuth permission screen — Claude requests access to your n8n instance.
8
Connector active — start building
The n8n connector now appears in your directory and is active in the Claude Code input bar. You can now ask Claude to build, validate, and deploy workflows directly on your instance.
n8n connector installed and visible in the Claude connector directory.
Setup (Claude Code — CLI):
claude mcp add --transport http n8n-mcp https://<your-n8n-domain>/mcp-server/http
Enable instance-level MCP in your n8n instance first: Settings → Instance-level MCP. Full tool reference: n8n MCP tools reference
VH3-managed instances: Your n8n URL is https://{your-company}.n8n.vh3.ai. The n8n-nodes-vh3ai community node and VH3 credentials are pre-installed. Contact VH3 support if you need your MCP access token or API key.
The official n8n MCP knows n8n’s built-in nodes and the Workflow SDK. It does not know the VH3 AI community node — its resources, operations, routing rules, or patterns. Without this document, an AI assistant will not know:
Which resource and operation to choose for a given question (section 5)
That jobFeed should be preferred over jobs for reads (section 3d)
The correct timeAxis for performance vs intake questions (section 4)
How General Email and Portal Email ingest results route downstream (section 6.8)
That custom field IDs must be fetched from the job type first (section 10)
The exact node type name (n8n-nodes-vh3ai.vh3Ai) and credential type (vh3AiApi)
Attach this document at the start of any session where you are building VH3 AI workflows. Combined with the n8n connector, this is the complete stack.
Optional: czlonkowski/n8n-mcp (Cursor and offline authoring)
czlonkowski/n8n-mcp is a separate community MCP server. It is not what the official Claude n8n connector uses, and is not required for the build experience described above.Consider it if you are working in Cursor or another editor, want stricter pre-deploy validation, or need offline node schema lookup without a live n8n connection. It uses different tool names (n8n_create_workflow, get_node, etc.) and requires a one-time install via npx or Docker.Setup: github.com/czlonkowski/n8n-mcp
The node exposes 38 resources split across three internal API layers. This split is invisible in the UI but critical for understanding timeout, latency, and data freshness expectations.
These map directly to the BigChange field-service platform. Operations are typically fast (<2 s). The resource values are used in $parameter["resource"].
Display name
resource value
What it covers
Job (BigChange)
jobs
CRUD, schedule, start, set result, cancel, manage stock constraints
Contact (BigChange)
contacts
Companies and sites — create, read, update, delete
Resource / Engineer (BigChange)
resources
Engineers/technicians and their groups
Job Type (BigChange)
jobTypes
Job type templates (installation/repair/maintenance schemas)
Vehicle (BigChange)
vehicles
Fleet vehicles — read/create/update records and groups
Worksheet (BigChange)
worksheets
Mobile worksheet definitions, questions, and submitted answers
Worksheet Group (BigChange)
worksheetGroups
Folders that organise worksheet definitions
Invoice (BigChange)
invoices
Sales invoices and line items
Note (BigChange)
notes
Notes/tasks/updates on jobs, contacts, and persons
Person (BigChange)
persons
Individual people attached to a contact (site contacts, consent history)
When both a BigChange resource and a VH3 AI intelligence resource can answer the same question, prefer the intelligence layer.The FSI layer ingests and enriches all job data continuously. For read operations — job feeds, aggregations, search, analysis, monitoring — it is faster (often cached), returns richer data, and avoids unnecessary load on the BigChange API.
Question
Prefer
Reason
List or search jobs
jobFeed (VH3 AI) over jobs (BigChange)
Enriched, cached, supports aggregation
List customers with operational context
contactFeed (VH3 AI) over contacts (BigChange)
Snapshot plus optional customer summary
What needs attention?
sentinel (VH3 AI)
Pre-computed, no extra API calls
Business health snapshot
pulse (VH3 AI)
Cached dashboard, single call
Find a customer by name
search → autocomplete (VH3 AI)
Fuzzy match, no ID required
Historical job analysis
jobFeed → aggregateJobs (VH3 AI)
Built-in metrics, period comparison
The intelligence layer does not write to BigChange. To create or modify FMS records — jobs, contacts, invoices, notes — use the BigChange CRUD resources (section 3a). Cases, Teams, Quote Documents, and Salma estimates write on the VH3 tenant API.
Default to actualStartAt for any performance or workload question. It reflects real field activity and excludes jobs that were planned but never worked.
Question type → Recommended time axis─────────────────────────────────── ────────────────────────How many jobs did we complete? actualStartAt / actualEndAtWhat's our first-visit fix rate? actualStartAtHow many jobs came in this week? createdAtFinished late / overrun counts actualEndAt + finishedLate=trueStarted late / late arrivals actualStartAt + startedLate=trueWhat's in the schedule for today? plannedStartAtHow long do jobs take? actualStartAt → actualEndAt delta
createdAt includes jobs that were planned but never attended. Do not use it for performance analysis unless the user is explicitly asking about intake volume or pipeline.
Partial periods: When the current period (e.g. this_week) is still in progress, say so before drawing conclusions. The compareTo parameter (previous_period, same_period_last_week, same_period_last_month) handles apples-to-apples comparison automatically — prefer it over inventing date ranges.
Retrieves all stored CustomerSummary sections. Set fullReport: true for assembled markdown.
Date filtering on searchOutcomes and intake operations is applied client-side after the API responds. Set maxAgeMonths to limit result age. searchOutcomesEnriched applies date, status, and result filters server-side. Existing searchOutcomes workflows are unchanged.
For scheduled automations, use getSentinelResults (cached, instant) rather than runSentinels (re-computes) to avoid latency in time-sensitive triggers.
subject + emailBody + senderAddress required. Supports attachment via URL or binary data.
batchClassifyEmail
JSON array of up to 50 email objects. Portal/pre-filter hits are instant; novel emails consume LLM tokens.
ingestGeneralEmail
Runs a non-portal email through full extraction and review. Uses the same fields and attachment options as Portal Ingest.
ingestEmail
Extracts structured job data from recognised FM portal emails. Returns resolved entities and a status field.
listTriageCategories
Returns active categories with priority, destination, and prompt rules.
listTaxonomyRules
Filter by phase: pre_classify (noise filters) or post_classify (routing decisions).
Both ingest operations return the same status values. Always switch on status downstream:
Status
Meaning
auto_created
New work passed the confidence checks. Use the returned job preview and creation result.
classified
The email was understood, but it does not require a new job.
pending_review
Customer, site, type, or other job details need human review.
unprocessable
The email did not contain enough reliable information to continue.
Attachments: General Email and Portal Email ingest accept files by URL or from n8n binary data. Supported work-order attachments can be sent with the email, so a separate Extract From File step is not required.
Generates structured pre-visit briefing + call script. Use jobPayload (JSON) if the job was created very recently and may not yet be indexed in the intelligence layer.
Quote Run estimate for a job. Recipient emails must be supplied on the node; they are not taken from the site contact. Optional contactId, additionalGuidance, jobPayload, rateSetContactId.
Because usableAsTool: true is set, the node can be attached directly to an AI Agent node as a tool. The agent reads each operation’s description field at runtime to decide which to call.
System prompt: Copy the system message from /agent-kits/n8n-agents. It encodes the time-axis rules, identity scoping, and response format. Do not re-describe parameter enums in the system prompt — they live in the tool descriptions already.
Memory: Use Buffer Window with contextWindowLength: 10. Set sessionKey to the channel ID or user ID so follow-up queries retain context.
Timeouts: Set the VH3 AI Tool timeout to ≥ 30 s. Investigation and narrative reports regularly take 20–25 s; default short timeouts will fail silently.
Token cost: Each tool call adds tokens. Prefer fast operations (search, jobFeed, contactFeed, sentinel) in high-frequency triggers. Reserve investigate, reports, and salma for steps that genuinely need language synthesis.
Combining the VH3 AI Tool with other LangChain sub-nodes
Complex ingestion workflows often pair the VH3 AI Tool with other LangChain nodes in the same agent or as adjacent steps. A common pattern is using the Information Extractor node (with a lightweight model such as Gemini Flash) to extract typed custom field values from unstructured email or document text — using the custom field schema fetched from Job Types at runtime to build the extraction prompt. This keeps field extraction data-driven rather than hardcoded to a specific job type, and handles schema changes without workflow edits. See Pattern F in section 9.
Schedule trigger (07:00) → VH3 AI: Sentinel — Run Sentinels (all) → IF node: triggered alerts > 0 → Slack: post formatted alert list → [else] Slack: post "All clear"
Pattern F: FM portal email → job creation with custom field extraction
This is the core portal ingestion pattern. The key non-obvious steps are the PDF/HTML split, the Information Extractor for custom fields, and the Wait + verify step that handles indexing lag between BigChange creation and FSI visibility.
Outlook trigger (new email) → Set node (centralised config: job type IDs, default contact, etc.) → Switch: has PDF attachment? → [PDF] Get Binary Attachment → Extract From File (PDF→text) → [HTML] extract body text → VH3 AI: Email — Ingest Portal Email (emailText + preferredTypeIds from config) → Switch: ingestEmail.status → "auto_created": → VH3 AI: Job Type — Get All (fetch schema for matched type) → Information Extractor LLM node (Gemini Flash) prompt built from job type custom field definitions + email text → Code: assemble job payload with extracted custom field values → VH3 AI: Jobs — Create → Wait (30 s — allow FSI indexing) → VH3 AI: Job Feed — Get Enriched Job (lightweight verify) → Reply email: confirmation with job reference → "pending_review": send to human approval queue (email / Slack) → "classified": record the result and exit → "unprocessable": log to spreadsheet / case and exit
Webhook / job-complete trigger → VH3 AI: Salma — Generate Estimate (jobId + recipients) → VH3 AI: Quote Document — List / Get Document → Email or Slack: notify estimator with the draft
Any workflow with more than two configurable values — type IDs, contact IDs, email addresses, Slack channels — should centralise them in a Set node at the start. This makes the workflow easy to adapt per tenant without hunting through individual node parameters.
Converting spreadsheet rows into synthetic portal email bodies lets the same ingestEmail pipeline handle both live emails and bulk imports without duplicating job creation logic.
Form trigger (file upload — xlsx or csv) → Switch: file format → Extract From File (xlsx) / Extract From File (csv) → Code: build synthetic portal email body from each row → Split in Batches (configurable batch size, e.g. 5) → VH3 AI: Email — Ingest Portal Email (per row) → Switch: status → "auto_created" path (same as Pattern F) / record result → [loop continues] → Summary email: total created / review / failed
Never expose internal IDs in agent replies. Use job references, engineer names, customer names, and site addresses.
companyId in credentials is required for VH3 AI Intelligence operations and single-record BigChange operations.
simplify: true (where available) strips null, empty string, and empty array fields from responses — recommended when passing data downstream.
returnAll: true on list operations uses automatic pagination. Only use it when you genuinely need the full dataset; large tenants can have thousands of jobs.
Batch email classification (batchClassifyEmail) is significantly more efficient than calling classifyEmail in a loop. Use it whenever you have multiple emails to process in the same step.
Binary data in workflows. Any workflow that handles file attachments (PDFs, spreadsheets, images) should have Binary mode set to Filesystem in the workflow settings. Without this, binary payloads are stored inline with execution records, which causes memory pressure and can silently fail on large files. Set this before building any attachment-handling or import workflow.
Any operation that creates, updates, deletes, cancels, or transitions a BigChange record is irreversible or difficult to undo. Before generating a workflow that includes these operations:
Confirm intent explicitly with the user — do not infer that a write is needed from context alone.
Check for existing records before creating. Duplicate jobs, contacts, or invoices are a common source of data quality problems.
Scope updates narrowly — patch only the fields the user specified. Do not reset or overwrite fields that were not mentioned.
If you are unsure about the correct approach for a write operation, say so and ask the user rather than proceeding on an assumption.
BigChange jobs support custom fields whose schema is defined per job type. The available fields, their IDs, and their value types vary by tenant configuration.
Before constructing a Create Job or Update Job payload that includes custom fields, always fetch the job type first using Job Type (BigChange) → getAll and inspect the returned custom field definitions. Do not guess field IDs or types — they are not portable between job types or tenants.
The same principle applies to other entities with custom field support (contacts, resources). If you are unsure whether custom fields are involved, ask.
Avoid high-frequency polling loops with expensive operations. investigate, generateReport, and generateBriefing are not suitable for loops that run more than once per trigger event.
For sentinel monitoring, prefer getSentinelResults (cached, returns pre-computed results instantly) over runSentinels (re-computes) in any schedule that runs more than once or twice per day.
Where BigChange supports webhooks or event-based triggers, use them in preference to polling on a tight schedule.
If a workflow needs to wait for a job status to change, use a wait/delay node with a reasonable interval rather than a tight loop.
Hardcoded dates make workflows brittle. Use n8n’s Luxon-based $now expression for any date that should be calculated at runtime.
Today (ISO): {{ $now.toISO() }}Start of today: {{ $now.startOf('day').toISO() }}7 days ago: {{ $now.minus({ days: 7 }).toISO() }}Start of this week: {{ $now.startOf('week').toISO() }}Start of last month: {{ $now.minus({ months: 1 }).startOf('month').toISO() }}End of last month: {{ $now.minus({ months: 1 }).endOf('month').toISO() }}YYYY-MM (for reports): {{ $now.minus({ months: 1 }).toFormat('yyyy-MM') }}
Use these patterns when populating dateFrom, dateTo, startDate, endDate, and month fields. Never hardcode a date string in a workflow intended to run on a schedule.
When building workflows for a specific tenant or user, notice patterns that emerge in how they describe their work:
Preferred job statuses, result values, or engineer groupings they always filter by.
Specific customers or sites they monitor closely.
Report cadences and delivery channels they rely on.
Naming conventions for workflows, notes, and cases.
Where the same preference appears more than once, consider surfacing it as a workflow-level variable or a dedicated config node at the top of the workflow rather than embedding it in multiple node parameters. This makes the workflow easier to adapt without hunting through individual nodes.If you observe a pattern that suggests a repeating automation opportunity (e.g. the user manually runs the same report every Monday), point it out and offer to formalise it.
The subtitle expression on the node is:
={{$parameter["operation"] + " (" + $parameter["resource"] + ")"}} — you do not need to set it manually in JSON.
