> 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/mcp-servers.md).

# MCP servers

Connect an MCP server to the AI node so the model can use tools of other systems — CRM, order systems, ticketing, the knowledge base indexer.

**MCP (Model Context Protocol)** is an open standard for giving an AI model access to tools of other systems. An MCP server publishes a list of tools — each with a name, a description and the inputs it expects. The AI node offers the tools you enable to the model, and the model decides on its own when to call them, for example to look up an order, create a ticket or search the knowledge base.

MCP servers are available only in **AI node 2.0**.

{% hint style="warning" %}
Connect only MCP servers that are approved for your project (built by Born Digital or by your organization). A tool can read and change data in the connected system on behalf of the conversation.
{% endhint %}

## Add an MCP server

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2F9bHuSI3h92Nka9ze5eL7%2Fai-node-mcp-add.png?alt=media&amp;token=a2f4a27b-7c42-4ba6-9260-641ab4d8bc0f" alt="A new MCP server before Connect"><figcaption><p>A new MCP server before Connect</p></figcaption></figure>

1. Open the AI node, tab **Essential → MCP servers**, and click **+ Add**.
2. Click the new chip **MCP server** to open its settings.
3. In **API call**, choose **Local** or **Cloud** (see below). Keep **Local** unless you have a reason for Cloud.
4. Enter the server **URL** (must start with `http://` or `https://`).
5. If the server requires it, switch on **Authentication**, choose **API Key**, **Bearer** or **Basic** and enter the **Token**.
6. Click **Connect**. The name the server reports appears as the server name and on the chip, and its tools appear in **MCP tools**.
7. In **MCP tools**, keep checked only the tools the model should use in this node.
8. Close the editor and train the project.

{% hint style="info" %}

* The server name cannot be typed — it comes from the server on **Connect**. A server that was added but never connected blocks closing the editor with *"MCP server is missing a label."*
* The URL is locked while the server is connected. Click **Disconnect** to change it.
* The switch on the chip turns the server off without deleting it. A server that is switched off or disconnected is not used.
  {% endhint %}

## Local or Cloud

**API call** decides who calls the MCP server.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FQ3CZEAYuXx8RaZc2l8xX%2Fai-node-diagram-local-cloud.png?alt=media&amp;token=996e4caf-3342-4471-aa5f-1bcf978a4413" alt="Local and Cloud MCP servers"><figcaption><p>Local and Cloud MCP servers</p></figcaption></figure>

|                                              | **Local** (default)                                                                                                                                                                                         | **Cloud**                                                    |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Who calls the server                         | The Born Digital platform, during the conversation                                                                                                                                                          | The LLM provider (for example OpenAI), during the model call |
| The server must be reachable from            | The platform — internal addresses such as `http://indexer:8000/mcp/` work                                                                                                                                   | The public internet                                          |
| Conversation context passed to the server    | Organization, project and knowledge-base scope (see [Indexer MCP server](https://docs.borndigital.ai/digital-agent/conversation-flow/nodes-explained/ai-node/indexer-mcp-server.md)) plus the headers below | Only the headers below                                       |
| Headers on every call                        | `X-Conversation-Id`, `X-Interaction-Id`                                                                                                                                                                     | `X-Conversation-Id`, `X-Interaction-Id`                      |
| Widgets and files returned by tools          | Supported                                                                                                                                                                                                   | Not supported                                                |
| Tool calls recorded in the response variable | Yes                                                                                                                                                                                                         | Yes, unless the same node also uses a connected Local server |

The `X-Conversation-Id` and `X-Interaction-Id` headers let the owner of the MCP server find the conversation in the platform logs.

{% hint style="warning" %}
Cloud servers whose tools require a manual approval before each call are not supported.
{% endhint %}

## Choose the tools

After **Connect**, **MCP tools** lists every tool of the server with its description.

* On the first connect, all tools are checked. Uncheck the ones this node does not need: fewer tools mean a smaller request, lower cost and fewer wrong tool choices.
* When you reconnect later, tools that the server added in the meantime appear **unchecked**.
* Only checked tools are offered to the model.

Write in the [Instructions](https://docs.borndigital.ai/digital-agent/conversation-flow/nodes-explained/ai-node/essential-tab.md) when the model should use which tool. The model sees the tools under a name made of the server name and the tool name (for example `indexer__search_knowledge_base`).

## What happens during a conversation

* At every run of the node, the platform connects to each Local server and reads its tool list. If a server is not reachable, its tools are left out for that turn and the node continues without them.
* A tool call that fails is reported to the model as an error, so it can apologise or try something else. The error is also recorded in the response variable.
* Every request to the server uses the node **Timeout** (Configuration tab).
* Tool calls of the turn are stored in the response variable: `mcp_call` (the last call), `mcp_calls` (all calls of this turn) and `mcp_list_tools` (the tools that were offered). See [Response variable and routing](https://docs.borndigital.ai/digital-agent/conversation-flow/nodes-explained/ai-node/response-variable-and-routing.md).

## Widgets and files from MCP tools (Local only)

An MCP server built for Digital Studio can return more than text:

* **Bubble widget** – a tool returns a widget (for example a product card or a form) that the chat bubble renders. The model receives only a short summary of the widget; the widget itself is added to the node output, before or after the text. If the tool also supplies an assistant text, it replaces the model's answer. Only the first widget of a turn is shown.
* **Files** – a tool returns files (images, PDFs). They are given to the model within the same turn so it can read them, and are not stored in the conversation history. Up to 5 files per tool result and 20 MB per file.

Both formats are a contract between the MCP server and the platform; ask your Born Digital contact for the specification when building such a server.

## Troubleshooting

| Message or symptom                        | What to check                                                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| *Missing URL* / *Invalid URL*             | The URL must start with `http://` or `https://`.                                                                         |
| *Request failed with status code 307*     | The server redirects to another address — usually the same URL with a trailing slash. Add the `/` at the end of the URL. |
| *Connection failed. Try reconnecting.*    | URL, authentication, and whether the server is reachable — from the platform for Local, from the internet for Cloud.     |
| *Unable to load Tools. Try reconnecting.* | The server answered but its tool list could not be read. Reconnect; if it persists, contact the server owner.            |
| *MCP server is missing a label.*          | Click **Connect** on the server, or delete it.                                                                           |
| The model never calls a tool              | Is the tool checked in **MCP tools**? Do the Instructions say when to use it?                                            |
| The model calls the wrong tool            | Uncheck tools the node does not need and make the Instructions more specific.                                            |
