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

> Discover how n8n-mcp node property filtering streamlines AI agent workflows by extracting essential properties, significantly reducing token usage while maintaining crucial configurations.

- Repository: [Romuald Członkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp)
- Tags: deep-dive
- Published: 2026-03-24

---

**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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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:

```typescript
'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`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools.ts). Developers can programmatically access the essential property extraction as follows:

```typescript
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:

```typescript
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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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.