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

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 (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 (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 (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 (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:

// 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:

{
  "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:

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:

{
  "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 with the tool schema defined in 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 (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.

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