[Agent Builder] MCP tool and bulk import documentation

explore-analyze/ai-features/agent-builder/tools.md

@@ -70,7 +70,7 @@ You can extend the built-in tool catalog with your own custom tool definitions.
 
 - **[Index search tools](tools/index-search-tools.md)**: Define tools that are scoped to a specific index or pattern, allowing the LLM to decide how to query those indices based on the user's request.
 - **[ES|QL tools](tools/esql-tools.md)**: Define tools with explicit {{esql}} queries for precise, pre-defined data retrieval operations.
-
+- **[MCP tools](tools/mcp-tools.md)**: Define tools that map to a remote Model Context Protocol (MCP) server's tools, allowing an LLM to leverage the server during chat sessions.
 
 This flexibility allows you to create tools that match your specific use cases and data access patterns.
 
@@ -111,8 +111,8 @@ You can create custom tools to help agents interact with your data in specific w
 
 4. Fill in the required fields:
    - **Name**: Enter a descriptive name for your tool.
-   - **Description**: Write a clear explanation of what the tool does and when it should be used.
-   - **Tool type**: Choose either **[{{esql}}](tools/esql-tools.md)** or **[Index search](tools/index-search-tools.md).**
+   - **Description**: Write a clear explanation of what the tool does and when it should be used. For MCP tools, this will be auto-populated with the description provided by the MCP server.
+   - **Tool type**: Choose **[{{esql}}](tools/esql-tools.md)**, **[Index search](tools/index-search-tools.md).** or **[MCP](tools/mcp-tools.md)**
    - **Parameters**: For tools with {{esql}} queries, define any parameters your query needs.
    - **Tags**: (Optional) Add labels to categorize and organize your tools.
 5. Choose how to save your tool:

explore-analyze/ai-features/agent-builder/tools/mcp-tools.md

@@ -0,0 +1,108 @@
+---
+navigation_title: "MCP tools"
+applies_to:
+  stack: preview 9.3
+  serverless: preview
+---
+
+
+
+# Model Context Protocol (MCP) tools
+
+Agent Builder MCP tools enable calling a remote [MCP server's](https://modelcontextprotocol.io/docs/learn/server-concepts) tools in your agent [chat](../chat.md). When you call an Agent Builder MCP tool, it calls the associated tool on the MCP server and returns its result.
+
+## Prerequisites
+
+To use external MCP tools, you first need to set up an [MCP Kibana Stack Connector](kibana://reference/connectors-kibana/mcp-action-type.md). This interface enables Agent Builder MCP tools to communicate with a remote MCP server.
+
+## Adding MCP tools
+
+### Adding a single tool
+
+Once an MCP Kibana Stack Connector has been set up, an MCP tool can be created by clicking "New tool" on the [Tools](/explore-analyze/ai-features/agent-builder/tools.md) landing page.
+
+:::{image} ../images/mcp-createnewtool-config-example.png
+:screenshot:
+:alt: Example configuration for a new MCP tool with the Context7 MCP server.
+:width: 800px
+:::
+
+MCP tools have the following configuration:
+
+MCP Server
+:   The MCP Kibana Stack Connector to interface with.
+
+Tool
+:   The specific tool on MCP server to create an Agent Builder MCP tool for.
+
+Once a tool is selected, the `Description` field of the tool automatically populates with the description provided by the MCP server.
+
+### Bulk import MCP tools
+
+Agent Builder provides an efficient way to import multiple tools from an MCP server using the `Bulk import MCP tools` feature, which can be found in the Agent Builder [Tools](/explore-analyze/ai-features/agent-builder/tools.md) landing page under the "Manage MCP" dropdown.
+
+:::{image} ../images/mcp-bulkimport-location.png
+:screenshot:
+:alt: How to bulk import MCP tools from an MCP server.
+:width: 500px
+:::
+
+Configuration for importing tools in bulk, while similar to single MCP tool creation, has some extra fields and automated behavior to consider.
+
+:::{image} ../images/mcp-bulkimport-config-example.png
+:screenshot:
+:alt: Example configuration for bulk importing MCP tools from the Context7 MCP server.
+:width: 800px
+:::
+
+MCP Server
+:   The MCP Kibana Stack Connector to interface with.
+
+Tools to import
+:   The specific tools from the MCP server to import.
+
+Namespace
+:   A string to prepend to the tool name to aid in searching and organization. A namespace must start with a letter and contain only lowercase letters, numbers, and hyphens.
+
+Clicking "Import tools" generates a series of MCP tools that map to the associated MCP server tools that were selected.
+
+Imported tools have their `Tool ID` generated as `ramespace.tool-name`, where `namespace` is the user-provided namespace string, and `tool-name` is the name of the tool as provided by the MCP server. Furthermore, the `Description` field automatically populates.
+
+## How it works
+
+When an agent calls an MCP tool:
+
+1. Agent Builder retrieves the tool's input schema from the MCP Kibana Stack Connector.
+2. Agent Builder calls the MCP server tool with the required parameters.
+3. The MCP server returns the result directly to the LLM with no post-processing.
+4. The LLM interprets the result for the user.
+
+## Monitoring tool health
+
+MCP tools have built-in health monitoring. Tools that are unhealthy display an icon next to their IDs in the [Tools](/explore-analyze/ai-features/agent-builder/tools.md) landing page.
+
+An MCP tool is marked "unhealthy" when:
+
+* The MCP tool's associated MCP Kibana Stack Connector is unavaiable.
+
+    :::{image} ../images/mcp-connector-unavailable.png
+    :screenshot:
+    :alt: Connector unavailable icon.
+    :width: 100px
+    :::
+
+* The MCP tool's associated tool on the MCP server no longer exists.
+
+    :::{image} ../images/mcp-tool-not-found.png
+    :screenshot:
+    :alt: Tool not found icon.
+    :width: 100px
+    :::
+
+* The MCP tool's execution failed.
+
+    :::{image} ../images/mcp-tool-execution-failed.png
+    :screenshot:
+    :alt: Tool execution failed icon.
+    :width: 100px
+    :::

explore-analyze/toc.yml

@@ -182,6 +182,7 @@ toc:
             children:
               - file: ai-features/agent-builder/tools/esql-tools.md
               - file: ai-features/agent-builder/tools/index-search-tools.md
+              - file: ai-features/agent-builder/tools/mcp-tools.md
           - file: ai-features/agent-builder/programmatic-access.md
             children:
                - file: ai-features/agent-builder/kibana-api.md
@@ -386,4 +387,4 @@ toc:
           - file: alerts-cases/cases/manage-cases.md
           - file: alerts-cases/cases/manage-cases-settings.md
           - file: alerts-cases/cases/cases-as-data.md   
-  - file: numeral-formatting.md
+  - file: numeral-formatting.md