# How to Use `search_nodes` with `includeExamples` to Retrieve Configuration Samples

> Learn how to use search_nodes with includeExamples to get real n8n configuration samples. Augment your results with up to two examples per node.

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

---

**Setting the `includeExamples` parameter to `true` when calling the `search_nodes` MCP tool augments each n8n node result with up to two real-world configuration examples from the `template_node_configs` database, adding approximately 200–400 tokens per example to the response payload.**

The n8n-mcp repository implements a Model Context Protocol (MCP) server that exposes n8n workflow capabilities to AI agents and external clients. When you need concrete configuration patterns rather than just node metadata, using `search_nodes` with `includeExamples` retrieves actual JSON configurations from production workflow templates stored in the database.

## Understanding the `search_nodes` Tool and `includeExamples` Parameter

`search_nodes` is a core MCP tool that enables AI systems to discover n8n nodes by keyword search. The optional boolean **`includeExamples`** flag defaults to `false` but, when enabled, triggers a secondary query that fetches high-ranking template configurations for each returned node.

According to the tool schema defined in [`src/mcp/tools.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools.ts) (lines 34–60), each example adds roughly **200–400 tokens** to the response. The human-readable documentation in [`src/mcp/tool-docs/discovery/search-nodes.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tool-docs/discovery/search-nodes.ts) (lines 8–27) further clarifies that these examples represent real-world usage patterns extracted from popular community workflows.

## Internal Implementation Flow

When you invoke `search_nodes` with `includeExamples: true`, the MCP server processes the request through five distinct phases:

### 1. Entry Point and Query Normalization

The server receives the tool call at the entry point in [`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts) (lines 1665–1670) and forwards it to the private `searchNodes` method. This method normalizes the query string and determines whether to use the FTS5 (Full-Text Search) engine or a fallback LIKE search, passing the `includeExamples` flag through the `options` object (lines 1669–1678).

### 2. FTS5 Result Assembly

In the FTS5 code path (`searchNodesFTS`), the server first assembles the base results including node metadata, relevance scores, and display names (lines 1626–1634). At this stage, the results contain only standard node information without configuration examples.

### 3. Example Retrieval Loop

If `options?.includeExamples` evaluates to truthy, the server executes a secondary query for each returned node. This query pulls the two highest-ranked template configurations from the `template_node_configs` table (lines 1629–1636), ensuring you receive the most relevant community patterns.

### 4. Example Transformation

The fetched rows undergo `JSON.parse` and are attached to the node object under an **`examples`** array. Each example object contains three properties: `configuration` (the actual JSON payload), `template` (the workflow name), and `views` (popularity metric) (lines 1639–1643).

### 5. Response Serialization

The final payload—containing the node list plus the optional `examples` arrays—is returned to the caller and logged for telemetry purposes (lines 1650–1654). The unit tests in [`tests/unit/mcp/search-nodes-examples.test.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/tests/unit/mcp/search-nodes-examples.test.ts) (lines 91–114) verify that examples are only attached when explicitly requested.

## Practical Code Examples

### Direct HTTP API Call

Use this JavaScript pattern when connecting directly to the MCP HTTP endpoint:

```javascript
// Replace with the URL where the MCP server is listening
const MCP_URL = 'http://localhost:5678/mcp';

async function searchNodes(query, limit = 5, includeExamples = true) {
  const payload = {
    tool: 'search_nodes',
    arguments: { query, limit, includeExamples },
  };
  const res = await fetch(MCP_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  const data = await res.json();
  console.log(JSON.stringify(data, null, 2));
}

// Example: find webhook nodes with two template configs each
searchNodes('webhook');

```

**Sample response snippet:**

```json
{
  "query": "webhook",
  "results": [
    {
      "nodeType": "nodes-base.webhook",
      "displayName": "Webhook",
      "description": "...",
      "examples": [
        {
          "configuration": { "path": "/example", "httpMethod": "POST" },
          "template": "Example Webhook – GitHub push",
          "views": 1243
        },
        {
          "configuration": { "path": "/order", "httpMethod": "GET" },
          "template": "Order receipt webhook",
          "views": 872
        }
      ]
    }
  ],
  "totalCount": 5
}

```

### Using the MCP Client Library

For TypeScript applications utilizing the n8n-mcp client:

```typescript
import { MCPClient } from 'n8n-mcp';

const client = new MCPClient({ endpoint: 'http://localhost:5678/mcp' });

async function demo() {
  const { results } = await client.search_nodes({
    query: 'database',
    limit: 3,
    includeExamples: true,
  });

  for (const node of results) {
    console.log(`🧩 ${node.displayName}`);
    if (node.examples) {
      node.examples.forEach((ex, i) => {
        console.log(`  Example #${i + 1} (from ${ex.template}):`);
        console.log(JSON.stringify(ex.configuration, null, 2));
      });
    }
  }
}

demo();

```

### AI Agent Integration

When constructing tool calls for Claude, ChatGPT, or similar agents:

```text
{
  "tool": "search_nodes",
  "arguments": {
    "query": "slack",
    "limit": 2,
    "includeExamples": true
  }
}

```

The agent receives a response containing node metadata plus an **`examples`** array that can be pasted directly into a new node configuration.

## When to Use `includeExamples`

Enable `includeExamples` in the following scenarios:

- **AI-assisted workflow authoring** – Provide concrete JSON snippets back to the language model for context-aware code generation.
- **Documentation generation** – Display nodes alongside ready-to-paste configuration samples.
- **Rapid prototyping** – Fetch a node and instantly see realistic payloads without navigating the n8n UI.

Because each example adds **200–400 tokens**, limit your result set to `5` or `10` nodes when using this flag to prevent context window overflow.

## Summary

- **`search_nodes`** is the primary MCP tool for discovering n8n nodes by keyword.
- The **`includeExamples`** boolean flag fetches up to two real-world configurations per node from the `template_node_configs` table.
- Implementation resides in [`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts) with the tool schema defined in [`src/mcp/tools.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools.ts).
- Examples add approximately **200–400 tokens** each; use modest `limit` values for large searches.
- Results include `configuration`, `template`, and `views` metadata for each example.

## Frequently Asked Questions

### What is the token cost of using `includeExamples`?

Each configuration example adds approximately **200–400 tokens** to the response payload. For a result set containing 5 nodes with 2 examples each, expect an additional 2,000–4,000 tokens compared to a standard metadata-only search.

### How many examples are returned per node?

The server returns **up to two** examples per node, selecting the highest-ranked entries from the `template_node_configs` table based on community popularity metrics (views).

### Does `includeExamples` work with both FTS5 and fallback search?

Yes. The flag is passed through the `options` object in [`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts) (lines 1669–1678) and honored in both the FTS5 code path (`searchNodesFTS`) and the legacy LIKE fallback, though the raw analysis specifically highlights the FTS5 implementation (lines 1626–1654).

### Where are the example configurations stored?

Real-world configurations are stored in the **`template_node_configs`** database table. When `includeExamples` is true, the server queries this table for each node result, parses the JSON, and attaches it to the response under the `examples` array.