Add MCP tool integration to customization guide

configs/config_web_frag_mcp.yml

@@ -0,0 +1,196 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# =============================================================================
+# Test config: Deep Researcher with MCP tool integration (basic, no auth)
+# This extends config_web_frag.yml by adding an MCP tool via mcp_tool_wrapper.
+#
+# The MCP tool connects to an external MCP server (for example, a financial
+# data service) and makes it available to the deep research agents alongside
+# the existing web search, paper search, and knowledge search tools.
+#
+# Prerequisites:
+#   - An MCP server running at the configured URL
+#   - NeMo Agent toolkit with MCP support: uv pip install "nvidia-nat[mcp]"
+# =============================================================================
+
+general:
+  use_uvloop: true
+  telemetry:
+    logging:
+      console:
+        _type: console
+        level: INFO
+
+  front_end:
+    _type: aiq_api
+    runner_class: aiq_api.plugin.AIQAPIWorker
+    db_url: ${NAT_JOB_STORE_DB_URL:-sqlite+aiosqlite:///./jobs.db}
+    expiry_seconds: 86400
+    cors:
+      allow_origin_regex: 'http://localhost(:\d+)?|http://127.0.0.1(:\d+)?'
+      allow_methods:
+        - GET
+        - POST
+        - DELETE
+        - OPTIONS
+      allow_headers:
+        - "*"
+      allow_credentials: true
+      expose_headers:
+        - "*"
+
+llms:
+  nemotron_llm_intent:
+    _type: nim
+    model_name: nvidia/nemotron-3-nano-30b-a3b
+    base_url: "https://integrate.api.nvidia.com/v1"
+    temperature: 0.5
+    top_p: 0.9
+    max_tokens: 4096
+    num_retries: 5
+    chat_template_kwargs:
+      enable_thinking: true
+
+  nemotron_llm:
+    _type: nim
+    model_name: nvidia/nemotron-3-nano-30b-a3b
+    base_url: "https://integrate.api.nvidia.com/v1"
+    temperature: 0.1
+    top_p: 0.3
+    max_tokens: 16384
+    num_retries: 5
+    chat_template_kwargs:
+      enable_thinking: true
+
+  gpt_oss_llm:
+    _type: nim
+    model_name: openai/gpt-oss-120b
+    base_url: https://integrate.api.nvidia.com/v1
+    temperature: 1.0
+    top_p: 1.0
+    max_tokens: 256000
+    api_key: ${NVIDIA_API_KEY}
+    max_retries: 10
+
+  nemotron_llm_deep:
+    _type: nim
+    model_name: nvidia/nemotron-3-super-120b-a12b
+    base_url: "https://integrate.api.nvidia.com/v1"
+    temperature: 1.0
+    top_p: 1.0
+    max_tokens: 128000
+    num_retries: 5
+    chat_template_kwargs:
+      enable_thinking: true
+
+functions:
+  web_search_tool:
+    _type: tavily_web_search
+    max_results: 5
+    max_content_length: 1000
+
+  advanced_web_search_tool:
+    _type: tavily_web_search
+    max_results: 2
+    advanced_search: true
+
+  # Knowledge Retrieval (see sources/knowledge_layer/KNOWLEDGE-LAYER-SETUP.md)
+  knowledge_search:
+    _type: knowledge_retrieval
+    backend: foundational_rag
+    collection_name: ${COLLECTION_NAME:-test_collection}
+    top_k: 5
+    rag_url: ${RAG_SERVER_URL:-http://localhost:8081}
+    ingest_url: ${RAG_INGEST_URL:-http://localhost:8082}
+    timeout: 300
+
+  # Paper Search (optional - requires SERPER_API_KEY)
+  # Uncomment the block below and set SERPER_API_KEY to enable academic paper search.
+  # paper_search_tool:
+  #   _type: paper_search
+  #   max_results: 5
+  #   serper_api_key: ${SERPER_API_KEY}
+
+  # =========================================================================
+  # MCP Tool: Connect to an external MCP server
+  # This example wraps a single tool from a remote MCP server using
+  # mcp_tool_wrapper. The MCP server must be running and serving the tool
+  # at the specified URL.
+  #
+  # To add tools from your own MCP server:
+  #   1. Replace the url with your MCP server's endpoint
+  #   2. Replace mcp_tool_name with the name of the tool on the MCP server
+  #   3. Update the description so the agent knows when to use this tool
+  #   4. Choose the appropriate transport: streamable-http (recommended) or sse
+  #   5. Add the tool name to the relevant agents' tools lists below
+  # =========================================================================
+  mcp_financial_data:
+    _type: mcp_tool_wrapper
+    url: ${MCP_SERVER_URL:-http://localhost:9901/mcp}
+    transport: "streamable-http"
+    mcp_tool_name: "get_financial_data"
+    description: "Retrieves financial data and market information. Use this tool when the research query involves financial analysis, stock data, or market trends."
+
+  intent_classifier:
+    _type: intent_classifier
+    llm: nemotron_llm_intent
+    tools:
+      - web_search_tool
+      # - paper_search_tool  # Uncomment if SERPER_API_KEY is set
+      - knowledge_search
+      - mcp_financial_data
+
+  clarifier_agent:
+    _type: clarifier_agent
+    llm: gpt_oss_llm
+    planner_llm: nemotron_llm
+    tools:
+      - web_search_tool
+      - knowledge_search
+      - mcp_financial_data
+    max_turns: 3
+    enable_plan_approval: true
+    log_response_max_chars: 2000
+    verbose: true
+
+  shallow_research_agent:
+    _type: shallow_research_agent
+    llm: gpt_oss_llm
+    tools:
+      - web_search_tool
+      - knowledge_search
+      - mcp_financial_data
+    max_llm_turns: 10
+    max_tool_iterations: 5
+
+  deep_research_agent:
+    _type: deep_research_agent
+    orchestrator_llm: gpt_oss_llm
+    researcher_llm: nemotron_llm_deep
+    planner_llm: gpt_oss_llm
+    max_loops: 2
+    tools:
+      # - paper_search_tool  # Uncomment if SERPER_API_KEY is set
+      - advanced_web_search_tool
+      - knowledge_search
+      - mcp_financial_data
+
+workflow:
+  _type: chat_deepresearcher_agent
+  enable_escalation: true
+  enable_clarifier: true
+  use_async_deep_research: true
+  checkpoint_db: ${AIQ_CHECKPOINT_DB:-./checkpoints.db}

docs/source/customization/index.md

@@ -14,6 +14,7 @@ SPDX-License-Identifier: Apache-2.0
 - **[Configuration Reference](./configuration-reference.md)** — Complete YAML schema with all parameters
 - **[Swapping Models](./swapping-models.md)** — Use different LLMs (hosted NIM, self-hosted NIM, mixing models)
 - **[Tools and Sources](./tools-and-sources.md)** — Enable, disable, and configure search tools
+- **[MCP Tools](./mcp-tools.md)** — Add external tools through Model Context Protocol
 - **[Knowledge Layer](./knowledge-layer.md)** — Add document retrieval (LlamaIndex or Foundational RAG)
 - **[Prompts](./prompts.md)** — Modify agent behavior through Jinja2 prompt templates
 - **[Human-in-the-Loop](./hitl.md)** — Configure the clarifier and plan approval workflow

docs/source/customization/mcp-tools.md

@@ -0,0 +1,140 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+# MCP Tools
+
+Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. You can use MCP to connect the AIQ Blueprint to external tools and data sources served by remote MCP servers, without writing any custom Python code. Since the AIQ Blueprint is built on the NVIDIA NeMo Agent toolkit, MCP integration is available through configuration.
+
+For the full MCP documentation, refer to the [NeMo Agent Toolkit MCP Client Guide](https://docs.nvidia.com/nemo/agent-toolkit/latest/).
+
+## Prerequisites
+
+Install MCP support if it is not already available:
+
+```bash
+uv pip install "nvidia-nat[mcp]"
+```
+
+## Adding an MCP Tool
+
+Use `mcp_tool_wrapper` to connect to an MCP server and wrap a single tool as a function. This is the simplest way to add an external tool to the deep researcher.
+
+### Step 1: Define the MCP tool in the `functions` section
+
+```yaml
+functions:
+  # ... existing tools (web_search_tool, paper_search_tool, and so on) ...
+
+  mcp_financial_data:
+    _type: mcp_tool_wrapper
+    url: "http://localhost:9901/mcp"           # URL of the MCP server
+    transport: "streamable-http"                # recommended transport
+    mcp_tool_name: "get_financial_data"         # name of the tool on the MCP server
+    description: "Retrieves financial data and market information. Use this tool when the research query involves financial analysis, stock data, or market trends."
+```
+
+**Transport options:**
+
+- `streamable-http` (recommended): modern HTTP-based transport for new deployments
+- `sse`: Server-Sent Events, supported for backwards compatibility
+- `stdio`: standard input/output for local process communication (use `mcp_client` instead of `mcp_tool_wrapper` for this transport)
+
+### Step 2: Add the tool to each agent's `tools` list
+
+The agents will not use the tool unless it appears in their `tools` list. Add it to the agents that should have access:
+
+```yaml
+functions:
+  intent_classifier:
+    _type: intent_classifier
+    tools:
+      - web_search_tool
+      - paper_search_tool
+      - knowledge_search
+      - mcp_financial_data
+
+  shallow_research_agent:
+    _type: shallow_research_agent
+    tools:
+      - web_search_tool
+      - knowledge_search
+      - mcp_financial_data
+
+  deep_research_agent:
+    _type: deep_research_agent
+    tools:
+      - paper_search_tool
+      - advanced_web_search_tool
+      - knowledge_search
+      - mcp_financial_data
+```
+
+## Wrapping Multiple Tools
+
+If the MCP server exposes multiple tools, define one `mcp_tool_wrapper` entry per tool:
+
+```yaml
+functions:
+  mcp_stock_quote:
+    _type: mcp_tool_wrapper
+    url: "http://localhost:9901/mcp"
+    transport: "streamable-http"
+    mcp_tool_name: "get_stock_quote"
+    description: "Returns the current stock price for a given ticker symbol."
+  mcp_earnings_report:
+    _type: mcp_tool_wrapper
+    url: "http://localhost:9901/mcp"
+    transport: "streamable-http"
+    mcp_tool_name: "get_earnings_report"
+    description: "Returns the latest earnings report for a given company."
+```
+
+## Dynamic Tool Discovery with `mcp_client`
+
+Instead of wrapping tools one by one, `mcp_client` can automatically discover and register all tools from an MCP server. This is placed under `function_groups` rather than `functions`:
+
+```yaml
+function_groups:
+  financial_tools:
+    _type: mcp_client
+    server:
+      transport: streamable-http
+      url: "http://localhost:9901/mcp"
+```
+
+All tools served by that MCP server become available using the function group name (`financial_tools`) in the agents' `tools` lists.
+
+A complete example config is available at `configs/config_web_frag_mcp.yml`.
+
+## Authenticated MCP Tools
+
+MCP tools that require OAuth2 authentication (for example, corporate Jira, Confluence, or internal data platforms) are not supported in the current version of the AIQ Blueprint. The NeMo Agent toolkit provides an `mcp_oauth2` authentication provider, but it is not yet compatible with the blueprint's backend and frontend. Support for authenticated MCP tools is planned for an upcoming release.
+
+For non-authenticated MCP servers, or MCP servers that use service account credentials (set through environment variables on the server side), use the `mcp_tool_wrapper` approach described above.
+
+## UI Limitations
+
+MCP tools added through the configuration file will be available to the agents at the backend level, but they will not automatically appear in the demo UI. Displaying custom MCP tools in the UI requires changes to both the backend and frontend. Built-in support for this is planned for an upcoming version. In the meantime, the demo UI source code is provided and can be modified to surface additional tools as needed.
+
+## Prompt Tuning
+
+Adding an MCP tool to the config makes it available to the agents, but the agents' prompts may not reference it. For the agents to use MCP tools effectively, you should tune the relevant prompts so that the agent knows when and how to invoke the new tool. Each customization is different: the prompt changes depend on the tool's purpose and how it fits into the research workflow.
+
+For example, if you add a financial data MCP tool, ensure the tool's `description` field clearly explains what it does and when to use it. The NeMo Agent toolkit agents use tool descriptions for routing decisions. A good description such as *"Retrieves real-time stock prices and financial statements. Use this tool for any questions involving company financials, stock performance, or market data."* helps the agent select it for the right queries.
+
+For more on prompt customization, refer to [Prompts](./prompts.md).
+
+## Discovering MCP Tools
+
+You can list the tools served by any MCP server:
+
+```bash
+nat info mcp --url http://localhost:9901/mcp
+```
+
+To get details about a specific tool:
+
+```bash
+nat info mcp --url http://localhost:9901/mcp --tool get_financial_data
+```