How n8n-mcp Node Property Filtering Extracts Essential Properties for AI Agents

n8n-mcp uses a dedicated PropertyFilter service to compress thousands of raw node parameters into a curated set of 20 or fewer essential properties, drastically reducing token usage while preserving workflow-critical configuration options.

The n8n-mcp project solves the challenge of presenting n8n's extensive node configurations to AI agents without overwhelming context windows. Through intelligent node property filtering, the system extracts only the most relevant fields—required parameters and commonly used options—transforming verbose node schemas into compact, AI-friendly structures defined in src/services/property-filter.ts.

The PropertyFilter Service Architecture

The core filtering logic resides in the PropertyFilter service located at src/services/property-filter.ts. This service acts as a transformation layer between n8n's raw node definitions and the MCP (Model Context Protocol) tools that expose node capabilities to AI models.

The service implements three primary operations:

• Deduplication of redundant property definitions
• Curated selection via the ESSENTIAL_PROPERTIES registry
• Heuristic inference for unmapped node types

Curated Essential Property Mapping

At lines 42-78 of src/services/property-filter.ts, a static map called ESSENTIAL_PROPERTIES declares which fields matter most for specific node types. This configuration separates properties into two tiers: required (mandatory for basic operation) and common (frequently used but optional).

For example, the HTTP Request node configuration specifies:

'nodes-base.httpRequest': {
  required: ['url'],
  common: ['method', 'authentication', 'sendBody', 'contentType', 'sendHeaders'],
  categoryPriority: [...]
}

This curated approach ensures that AI agents receive the url parameter as mandatory while surfacing authentication and method options as secondary configuration choices.

The Filtering Pipeline

The getEssentials(allProperties, nodeType) method (lines 110-138) serves as the public entry point for property extraction. This method executes a three-step pipeline to distill essential properties from raw node definitions.

Step 1: Deduplication

Before selection begins, the service calls deduplicateProperties() (lines 85-106) to remove duplicate definitions that share identical name and displayOptions values. This prevents AI agents from receiving redundant configuration options that would clutter the context window without adding value.

Step 2: Selection Logic

After deduplication, the method looks up the node type in ESSENTIAL_PROPERTIES. When a configuration exists, the service extracts:

• Required properties via extractProperties(..., config.required, true)
• Common properties via extractProperties(..., config.common, false), excluding any fields already marked as required

Step 3: Fallback Inference

If the node type lacks a curated entry, the pipeline falls back to inferEssentials() (lines 221-226). This heuristic method automatically identifies required boolean flags and simple visible fields, ensuring the system remains functional even for custom or newly added nodes.

Property Simplification and Structuring

Once the essential property names are identified, the extractProperties() method locates full definitions using findPropertyByName() (lines 260-287), which recursively searches through property collections to locate nested fields.

Each located property then passes through simplifyProperty() (lines 292-353), which transforms verbose n8n schema objects into SimplifiedProperty structures containing only AI-relevant fields:

• name, displayName, type — Basic identification
• description — Human-readable guidance extracted via extractDescription() and generateDescription()
• default, placeholder — Simple default values
• options — First 20 selectable options for enum fields
• expectedFormat — Special handling for resourceLocator types (mode/value structures)
• showWhen — Up to two display-condition rules governing visibility
• usageHint — Concise tips generated by generateUsageHint() for URLs, authentication, JSON, or code fields
• required — Boolean flag indicating mandatory status

The method returns a FilteredProperties object containing two arrays: required (high-priority mandatory fields) and common (optional but useful fields). This structure typically contains fewer than 20 total items, optimizing token consumption for LLM interactions.

Search and Discovery

For ad-hoc property discovery beyond the curated essentials, the searchProperties() method (lines 528-553) traverses the complete property tree. It scores matches based on name prefixes and description content, returning simplified results annotated with their hierarchical paths. This enables AI agents to locate specific configuration options when the curated set proves insufficient for complex workflows.

Integration with MCP Tools

The filtering service powers the get_node_essentials MCP tool exposed in src/mcp/tools.ts. Developers can programmatically access the essential property extraction as follows:

import { PropertyFilter } from './src/services/property-filter';

// Retrieve raw properties from the node parser
const allProps = await nodeParser.getNodeProperties('nodes-base.httpRequest');

// Extract the AI-optimized subset
const essentials = PropertyFilter.getEssentials(allProps, 'nodes-base.httpRequest');

console.log('Required fields:');
essentials.required.forEach(p => console.log(`- ${p.name} (${p.type})`));

console.log('\nCommon fields:');
essentials.common.forEach(p => console.log(`- ${p.name}`));

For searching across all available properties:

const matches = PropertyFilter.searchProperties(allProps, 'auth');
matches.forEach(m => {
  console.log(`${m.path}: ${m.displayName} – ${m.usageHint}`);
});

Both methods return simplified structures ready for JSON serialization and transmission to AI clients, ensuring that language models receive clean, context-efficient node configuration data.

Summary

• n8n-mcp node property filtering occurs in src/services/property-filter.ts through the PropertyFilter service class.
• The ESSENTIAL_PROPERTIES map (lines 42-78) defines required and common fields for high-priority node types like HTTP Request.
• deduplicateProperties() (lines 85-106) eliminates redundant definitions before selection begins.
• getEssentials() (lines 110-138) orchestrates the extraction, falling back to inferEssentials() (lines 221-226) for unmapped nodes.
• simplifyProperty() (lines 292-353) compresses full schema definitions into SimplifiedProperty objects containing only AI-relevant fields.
• The output separates properties into required and common arrays, typically totaling fewer than 20 items to minimize token usage.

Frequently Asked Questions

How does n8n-mcp determine which properties are essential?

The system consults the ESSENTIAL_PROPERTIES static map in src/services/property-filter.ts (lines 42-78), which explicitly lists required and common fields for specific node types. If a node type lacks a curated entry, the inferEssentials() method (lines 221-226) applies heuristics to identify required flags and visible simple fields automatically.

What is the SimplifiedProperty structure used in n8n-mcp?

SimplifiedProperty is a compressed representation of an n8n node parameter containing only fields necessary for AI agents: name, displayName, type, description, default, placeholder, options (limited to 20), expectedFormat, showWhen conditions, usageHint, and a required flag. This structure is generated by the simplifyProperty() method at lines 292-353.

How does the property deduplication process work?

Before selecting essentials, the deduplicateProperties() method (lines 85-106) removes duplicate property definitions that share identical name and displayOptions values. This ensures that subsequent lookups return unique fields rather than multiple copies of the same configuration option.

Can I search for properties not included in the essential set?

Yes. The searchProperties() method (lines 528-553) traverses the complete property tree and scores matches based on name prefixes and descriptions. It returns simplified results with their hierarchical paths, enabling discovery of specialized configuration options beyond the curated essential properties.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}