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

> Optimize token usage in n8n-mcp when fetching node details. Use minimal detail levels, avoid heavy flags and leverage SimpleCache for efficient lookups.

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

---

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

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

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