> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/conversation-flow/nodes-explained/ai-node/indexer-mcp-server.md).

# Indexer MCP server

Search the knowledge base through the platform's own MCP server: several indexes at once, hybrid search, label filters, pinned indexes, and the index chosen from a variable.

The knowledge base indexer of the platform is also an **MCP server**. Connected to an AI node, it gives the model the tool `search_knowledge_base`. Compared with the built-in [Knowledge base tool](https://docs.borndigital.ai/digital-agent/conversation-flow/nodes-explained/ai-node/tools.md), it can do more:

|                                                | Knowledge base tool | Indexer MCP server                                        |
| ---------------------------------------------- | ------------------- | --------------------------------------------------------- |
| Indexes per search                             | One                 | One or several (results are merged and ranked together)   |
| Index chosen                                   | In the editor       | From a flow variable — can change during the conversation |
| Search mode                                    | Semantic            | Semantic or hybrid (semantic + full-text)                 |
| Filter by document labels                      | No                  | Yes                                                       |
| Index from another project of the organization | No                  | Yes                                                       |
| Index always included in full ("pinned")       | No                  | Yes                                                       |
| Fills `kb_document_*` variables                | Yes                 | No — the call is recorded in `mcp_call`                   |

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FIPOy3PvqolAnXoLgjfJi%2Fai-node-diagram-indexer.png?alt=media&amp;token=5050b386-d82f-4c14-8a23-b54dd3879f33" alt="How one search through the Indexer MCP server works"><figcaption><p>How one search through the Indexer MCP server works</p></figcaption></figure>

The model sends only a search query. Which indexes are searched, and how, is decided by the flow variables described below — the model can neither see nor change them.

## Connect the indexer

1. In the AI node (2.0), open **Essential → MCP servers → + Add** and click the new chip.
2. **API call: Local.** (Cloud does not work: the indexer is not reachable from the internet, and the search settings are passed only to Local servers.)
3. **URL:** `http://indexer:8000/mcp/` — with the trailing slash. Without it, **Connect** fails with *Request failed with status code 307*.
4. **Authentication:** off.
5. Click **Connect**. The server reports the name `indexer`.
6. In **MCP tools**, keep only **search\_knowledge\_base** checked (see [Tools of the indexer](#tools-of-the-indexer)).
7. Set at least one index variable (next section) **before** the flow reaches the AI node.
8. Tell the model in the Instructions when to search, for example *"Before answering any question about our products, call search\_knowledge\_base. Answer only from the returned text."*

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FsvU8X7eLeEzUrdWoKxrA%2Fai-node-mcp-indexer-connected.png?alt=media&amp;token=20b23ba0-8e64-43db-9a8c-fb15494e60a5" alt="Indexer MCP server connected, only search_knowledge_base enabled"><figcaption><p>Indexer MCP server connected, only search_knowledge_base enabled</p></figcaption></figure>

{% hint style="info" %}
The URL above is the indexer address inside Born Digital cloud environments. For on-premise installations, ask your Born Digital contact for the address. The URL must contain the word `indexer` — that is how the AI node knows it should pass the variables below to the server.
{% endhint %}

## Variables

Set the variables as ordinary flow variables, for example in the **Variables** section of a MESSAGE node placed before the AI node: click **+ Add**, type the variable name in the top field and the value in the editor below, then **Save**. Text values are written in quotes, for example `'faq'`. The variable name must match exactly.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FCdUd7c3Hk2rpRavd5FaE%2Fai-node-indexer-variables.png?alt=media&amp;token=003a45a0-604f-48f2-85e3-8206b146bee7" alt="Indexer variables set in a MESSAGE node"><figcaption><p>Indexer variables set in a MESSAGE node</p></figcaption></figure>

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FF0JU84obvXz3s1vVe87t%2Fai-node-indexer-flow.png?alt=media&amp;token=0c36d1a7-4bd8-4f7b-8fe0-70783cb6b8da" alt="The MESSAGE node runs before the AI node"><figcaption><p>The MESSAGE node runs before the AI node</p></figcaption></figure>

### Which index to search

Set **exactly one** of these:

| Variable      | Value                                                         | Example          |
| ------------- | ------------------------------------------------------------- | ---------------- |
| `index_name`  | Name of one index of the project                              | `'faq'`          |
| `index_names` | Names of several indexes, as a comma-separated text or a list | `'faq, pricing'` |
| `index_id`    | ID of one index                                               | `2234`           |
| `index_ids`   | IDs of several indexes, comma-separated text or a list        | `'2234, 2235'`   |

Optional:

| Variable           | Value                                                                                                                 | Default                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `index_project_id` | ID of another project **of the same organization** that owns the index. Use it when several projects share one index. | The project of the conversation |

{% hint style="warning" %}
If two of the index variables are set at the same time (for example `index_name` from one part of the flow and `index_names` from another), the search fails and the model receives *"Knowledge base search is not configured correctly…"*. Variables keep their value for the rest of the conversation, so clear the one you no longer use by setting it to an empty text `''`.
{% endhint %}

### How to search

| Variable                   | Value                                                                  | Default       |
| -------------------------- | ---------------------------------------------------------------------- | ------------- |
| `top_k`                    | Number of snippets returned, 1–100                                     | 3             |
| `amount_adjacent_snippets` | Neighbouring snippets added to each hit, 0–5                           | 0             |
| `retrieval_mode`           | `'vector'` (semantic search) or `'hybrid_bm25'` (semantic + full-text) | `'vector'`    |
| `bm25_weight`              | Weight of the full-text part in hybrid search, 0.0–1.0                 | 0.4           |
| `labels`                   | Search only documents with these labels, comma-separated               | all documents |

* **Hybrid search** helps when users ask with exact terms — product names, codes, tariff names — that semantic search alone can miss. It applies to indexes stored by the platform; indexes stored at a cloud provider keep their own search.
* **Labels** are the document labels from the Knowledge base tab. They are case-sensitive.

### Pinned indexes

| Variable             | Value                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `pinned_index_names` | Names of indexes whose **whole content** is added to every search result, comma-separated |
| `pinned_index_ids`   | The same by index ID                                                                      |

A pinned index is not searched; its full content (all documents, all snippets in order) is appended after the search results on every search. Use it for small reference content the model must always have at hand, regardless of the question — a table of links, opening hours, a price list.

* The model still has to call `search_knowledge_base`; pinned content comes with the search result. A pinned index alone, without an index to search, does nothing.
* Keep pinned indexes small. Their content is cut at 100,000 characters by default and a note about the cut is added.
* The content is the concatenation of the index snippets. If the index was created with snippet overlap, the overlapping text appears twice — create pinned indexes with overlap 0.
* An unknown pinned index, or one from another project, is skipped; the search result is returned unchanged.

{% hint style="info" %}
Pinned indexes require the NLP Engine and Indexer releases from October 2026. If they have no effect in your environment, check with your Born Digital contact that these releases are deployed.
{% endhint %}

### How values are read

* Variables are read each time the flow enters the AI node, so set them in a node before it.
* A value that is not valid — for example `bm25_weight` of `2`, or an unknown `retrieval_mode` — is ignored and the default is used.
* If no index variable is set, the search tells the model that it is not configured.

## Examples

**One index**

| Variable     | Value   |
| ------------ | ------- |
| `index_name` | `'faq'` |

**Several indexes, hybrid search, more snippets**

| Variable         | Value                   |
| ---------------- | ----------------------- |
| `index_names`    | `'faq, pricing, terms'` |
| `retrieval_mode` | `'hybrid_bm25'`         |
| `bm25_weight`    | `0.3`                   |
| `top_k`          | `6`                     |

**Index chosen by topic** — the flow recognises the topic (for example with an ANSWER node), each branch sets `index_name` to `'billing'` or `'technical'`, and both branches lead to the same AI node.

**Search plus a pinned link table**

| Variable             | Value         |
| -------------------- | ------------- |
| `index_name`         | `'faq'`       |
| `pinned_index_names` | `'deeplinks'` |

The question *"When is the office open and where do I see my invoices?"* returns the matching FAQ snippets followed by:

```
=== Pinned knowledge base 'deeplinks' (full content) ===

# deeplinks.txt
Invoice overview: https://example.com/invoices
Change of advance payments: https://example.com/advances
```

## What the model receives

`search_knowledge_base` returns the found documents, each as the document name followed by its snippets, separated by `---`:

```
# office-hours.txt
The office in Prague is open Monday to Friday from 9:00 to 17:00.

---

# parking.txt
Parking is available in the courtyard.
```

If nothing matches, the model receives *"No relevant information found in the knowledge base."* The full call — query, settings and result — is recorded in `mcp_call` of the response variable.

## Tools of the indexer

| Tool                    | What it does                                                                                                             | Recommendation                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `search_knowledge_base` | Searches the indexes set in the variables.                                                                               | Keep checked.                                |
| `get_index_content`     | Returns an outline of one index: its documents, their descriptions, labels and snippet titles, without the snippet text. | Only for agents that should browse an index. |
| `get_document_content`  | Returns the full text of selected documents of one index.                                                                | Only together with `get_index_content`.      |

`get_index_content` and `get_document_content` work with **one** index only (`index_name` or `index_id`).

## Troubleshooting

| Symptom                                                        | Cause                                                                                                                                                 |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Knowledge base search is not configured correctly…"*         | No index variable is set, or two of them are set at once (for example `index_name` and `index_names`).                                                |
| The model does not search                                      | `search_knowledge_base` is unchecked, or the Instructions do not tell the model to search.                                                            |
| Results come from a different project's index of the same name | `index_project_id` points to another project.                                                                                                         |
| Variables seem to be ignored                                   | The server URL does not contain `indexer`, **API call** is set to Cloud, the variable name has a typo, or the variable is set only after the AI node. |
| *Request failed with status code 307* on **Connect**           | The URL is missing the trailing slash: use `http://indexer:8000/mcp/`.                                                                                |
| Pinned content is cut                                          | The pinned index is larger than 100,000 characters. Make it smaller or split the content.                                                             |
