How to Optimize Token Usage in n8n-mcp When Fetching Node Details

Use the detail parameter with "minimal" or "standard" levels, avoid heavy flags like includeTypeInfo and includeExamples unless necessary, and leverage the built-in SimpleCache for repeated lookups.

The czlonkowski/n8n-mcp repository provides a Model Context Protocol (MCP) server for n8n workflow automation, exposing node metadata through a unified get_node tool. Because this tool can generate JSON payloads exceeding 1,000 tokens, understanding how to optimize token usage in n8n-mcp is essential for keeping LLM context windows efficient and API costs low.

Use Progressive Detail Levels to Minimize Payload Size

The get_node tool implements progressive detail levels that control exactly how much schema information returns. According to the tool schema definition in src/mcp/tool-docs/configuration/get-node.ts (lines 20‑24), you can select from three distinct modes:

• detail: "minimal" (default) — Returns only nodeType, displayName, short description, and category. This generates approximately 200 tokens, roughly 95% smaller than a full dump.
• detail: "standard" — Returns core metadata plus required and common properties without heavy type information. This consumes approximately 400 tokens.
• detail: "full" — Returns complete property lists with type-info, validation rules, and examples, often exceeding 800‑1,000 tokens.

For routine node lookups, start with minimal. Only escalate to standard or full when the LLM explicitly requires deeper schema validation or property examples.

Leverage the Built-in Cache for Repeated Lookups

The server uses SimpleCache (imported at line 27 in src/mcp/server.ts) to store node essentials keyed by nodeType and the includeExamples flag. When you request the same node repeatedly within a session, the cache serves the stored result instantly.

The cache key construction follows this pattern:

// From src/mcp/server.ts
const cacheKey = `essentials:${nodeType}:${includeExamples ? 'withExamples' : 'basic'}`;

This design ensures that calls with includeExamples: true and includeExamples: false maintain separate cache entries, preventing payload contamination while maximizing cache hits for identical requests.

Disable Optional Heavy Payloads

Two boolean parameters significantly inflate token counts when enabled. Only activate these when the LLM specifically requests the data:

• includeTypeInfo: true — Adds 80‑120 tokens per property by injecting type structures and validation rules.
• includeExamples: true — Adds 200‑400 tokens per example by attaching real-world configuration snippets.

Additionally, use propertyQuery with mode: "search_properties" to return only matching property paths rather than the entire schema. This targeted approach dramatically reduces payload size when you need to locate specific fields like authentication or webhook settings.

Choose the Right Mode for Your Use Case

The mode parameter in get_node (defined in src/mcp/tools.ts at line 76) determines which data slice the server returns:

• mode: "info" (default) — Returns node metadata and property lists.
• mode: "docs" — Returns markdown documentation blocks (typically larger payloads).
• mode: "search_properties" — Returns filtered property paths based on your propertyQuery.
• mode: "versions", compare, breaking, or migrations — Returns version-related data (usually small).

Selecting a specific mode prevents the server from bundling unnecessary sections together. For quick metadata checks, always prefer "info" over "docs".

Practical Code Examples

The following patterns demonstrate how to minimize token consumption while retrieving node data from the czlonkowski/n8n-mcp server:

// 1. Minimal metadata (ideal for token-tight contexts)
await client.callTool('get_node', {
  nodeType: 'nodes-base.slack',
  detail: 'minimal',
  mode: 'info',
  includeTypeInfo: false,
  includeExamples: false
});

// 2. Standard essentials (formerly get_node_essentials)
// Maps to detail: "standard" as defined in src/mcp/handlers-n8n-manager.ts#L2099-L2101
await client.callTool('get_node', {
  nodeType: 'nodes-base.httpRequest',
  detail: 'standard',
  mode: 'info'
});

// 3. Focused property search - returns only matching paths
await client.callTool('get_node', {
  nodeType: 'nodes-base.httpRequest',
  mode: 'search_properties',
  propertyQuery: 'auth',
  maxPropertyResults: 10
});

// 4. Cached repeated lookup - automatically hits SimpleCache
await client.callTool('get_node', {
  nodeType: 'nodes-base.httpRequest',
  detail: 'minimal',
  mode: 'info'
});

The get_node_essentials tool referenced in older documentation now maps directly to get_node with detail: "standard" and mode: "info", utilizing the property filtering logic in src/services/property-filter.ts (line 471).

Summary

• Start with detail: "minimal" for all initial node lookups to consume only ~200 tokens.
• Use detail: "standard" (the modern get_node_essentials behavior) when you need required and common properties without heavy type metadata.
• Disable includeTypeInfo and includeExamples unless the LLM explicitly requires validation rules or configuration examples.
• Leverage SimpleCache by repeating identical calls within the same session; the server automatically serves cached results from src/mcp/server.ts.
• Select specific mode values like "info" or "search_properties" to avoid fetching unnecessary documentation or version data.

Frequently Asked Questions

What is the difference between detail: "minimal" and detail: "standard" in n8n-mcp?

detail: "minimal" returns only core metadata including nodeType, displayName, description, and category (~200 tokens), while detail: "standard" adds the list of required and common properties without type information or examples (~400 tokens). The standard level is suitable when you need to know which fields are mandatory but do not require full schema validation details.

How does the SimpleCache work in the n8n-mcp server?

The SimpleCache stores node essentials using a composite key of nodeType and the includeExamples flag, as implemented in src/mcp/server.ts. When you call get_node with the same parameters within a session, the server checks the cache first, avoiding redundant database queries and reducing both latency and token generation overhead.

When should I use the search_properties mode instead of info mode?

Use mode: "search_properties" when you need to locate specific property paths (such as authentication or pagination settings) without retrieving the entire node schema. This mode accepts a propertyQuery parameter and returns only matching results, cutting token usage by 80‑90% compared to fetching full property lists.

Does enabling includeExamples affect the cache behavior?

Yes. Because the cache key in src/mcp/server.ts explicitly includes the includeExamples flag (withExamples vs basic), enabling examples generates a separate cache entry. This prevents smaller "basic" payloads from being polluted with heavy example data, ensuring that token-optimized calls remain lean even when other sessions request examples for the same node.

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