feat: Add MCPToolset (#1626)

Co-authored-by: oryx1729 <oryx1729@protonmail.com>
Co-authored-by: Michele Pangrazzi <xmikex83@gmail.com>
Co-authored-by: Bilge Yücel <bilge.yucel@deepset.ai>
Co-authored-by: Sebastian Husch Lee <sjrl@users.noreply.github.com>

Author: 5 people

integrations/mcp/examples/google_maps_agent.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+### Overview
+# This script shows how to use the **Google Maps MCP Server** in combination with the **Haystack Agent** and **OpenAI's Chat Generator** to search for places via the Google Places API.
+
+# ---
+
+# ### 🔧 Step 1: Start the Google Maps MCP Server
+
+# Make sure you have a valid **Google Maps API key**.
+# See [Google Maps API Key](https://developers.google.com/maps/documentation/places/web-service/get-api-key) for more information.
+
+# Run the following Docker command to start the MCP Server locally on port 8000:
+
+# ```bash
+# docker run -it --rm -p 8000:8000 \
+#   -e GOOGLE_MAPS_API_KEY=$GOOGLE_MAPS_API_KEY \
+#   supercorp/supergateway \
+#   --stdio "npx -y @modelcontextprotocol/server-google-maps" \
+#   --port 8000
+# ```
+
+# ---
+
+# ### 🕵️ Step 2: Inspect Available Tools (Optional but useful)
+
+# You can verify that the MCP server is running and see the available tools using:
+
+# ```bash
+# npx -y @modelcontextprotocol/inspector
+# ```
+
+# Connect MCP Inspector to the server at `http://localhost:8000/sse` and click on "List Tools" to display tools such as:
+
+# - `maps_geocode`: Convert address → coordinates
+# - `maps_reverse_geocode`: Convert coordinates → address
+# - `maps_search_places`: Search places (e.g., restaurants)
+# - `maps_place_details`: Get details of a specific place
+# - `maps_distance_matrix`: Calculate travel distance/time
+# - `maps_elevation`: Get elevation info
+# - `maps_directions`: Get route directions
+
+# ---
+
+# ### ▶️ Step 3: Run the Python Script
+
+# This script sets up:
+# - A **Langfuse trace**
+# - A **MCPToolset** with selected tools (`maps_geocode`, `maps_search_places`)
+# - An **Agent** using `gpt-4.1` to process a natural language request
+
+# To run the script:
+
+# ```bash
+# python examples/google_maps_agent.py
+# ```
+
+# The agent will respond to this example query:
+
+# > "Find the five best Persian restaurants close to Zinnowitzer Str. 1, 10115 Berlin, Germany"
+
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+# from haystack_integrations.components.connectors.langfuse.langfuse_connector import LangfuseConnector
+from haystack_integrations.tools.mcp.mcp_tool import SSEServerInfo
+from haystack_integrations.tools.mcp.mcp_toolset import MCPToolset
+
+
+def main():
+    # tracer = LangfuseConnector("Agent google maps search")
+    # Optionally, you can use Langfuse to trace the agent's activity but it needs
+    # additional configuration.
+    # See [Langfuse integration](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse) for more information.
+    toolset = MCPToolset(
+        SSEServerInfo(base_url="http://localhost:8000"), tool_names=["maps_geocode", "maps_search_places"]
+    )
+    agent = Agent(chat_generator=OpenAIChatGenerator(model="gpt-4.1"), tools=toolset)
+    result = agent.run(
+        messages=[
+            ChatMessage.from_user(
+                text="Find the five best persian restaurants close to Zinnowitzer Str. 1, 10115 Berlin, Germany"
+            )
+        ]
+    )
+    print(result["messages"][-1].text)
+
+
+if __name__ == "__main__":
+    main()

integrations/mcp/examples/hayhooks/pipeline_wrapper.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.tools.mcp import MCPToolset, SSEServerInfo
+
+# This example demonstrates using MCPToolset with SSE transport
+# and filtering tools by name
+# Run this client after running the server mcp_sse_server.py
+# It shows how MCPToolset can selectively include only specific tools
+
+
+def main():
+    """Example of using MCPToolset with filtered tools."""
+
+    try:
+        print("Creating toolset with all available tools:")
+        # Create a toolset with all available tools
+        full_toolset = MCPToolset(
+            server_info=SSEServerInfo(base_url="http://localhost:8000"),
+        )
+
+        # Print all discovered tools
+        print(f"Discovered {len(full_toolset)} tools:")
+        for tool in full_toolset:
+            print(f"  - {tool.name}: {tool.description}")
+
+        print("\nCreating toolset with filtered tools:")
+        # Create a toolset with only specific tools
+        # In this example, we're only including the 'add' tool
+        filtered_toolset = MCPToolset(
+            server_info=SSEServerInfo(base_url="http://localhost:8000"),
+            tool_names=["add"],  # Only include the 'add' tool
+        )
+
+        # Print filtered tools
+        print(f"Filtered toolset has {len(filtered_toolset)} tools:")
+        for tool in filtered_toolset:
+            print(f"  - {tool.name}: {tool.description}")
+
+        # Use the filtered toolset
+        if len(filtered_toolset) > 0:
+            add_tool = filtered_toolset.tools[0]  # The only tool should be 'add'
+            result = add_tool.invoke(a=10, b=5)
+            print(f"\nInvoking {add_tool.name}: 10 + 5 = {result.content[0].text}")
+        else:
+            print("No tools available in the filtered toolset")
+
+    except Exception as e:
+        print(f"Error in filtered toolset example: {e}")
+
+
+if __name__ == "__main__":
+    main()

integrations/mcp/examples/mcp_filtered_tools.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.tools.mcp import MCPToolset, SSEServerInfo
+
+# This example demonstrates using MCPToolset with SSE transport
+# Run this client after running the server mcp_sse_server.py
+# It shows how MCPToolset automatically discovers and creates tools from the MCP server
+
+
+def find_tool(toolset, tool_name):
+    """
+    Find a tool by name in the toolset.
+
+    :param toolset: The toolset to search in
+    :param tool_name: The name of the tool to find
+    :returns: The tool if found, None otherwise
+    """
+    for tool in toolset:
+        if tool.name == tool_name:
+            return tool
+    return None
+
+
+def main():
+    """Example of using MCPToolset with SSE transport."""
+
+    try:
+        # Create the toolset - this automatically discovers all available tools
+        # from the MCP server and creates Tool instances for each one
+        sse_toolset = MCPToolset(
+            server_info=SSEServerInfo(base_url="http://localhost:8000"),
+        )
+
+        # Print discovered tools
+        print(f"Discovered {len(sse_toolset)} tools:")
+        for tool in sse_toolset:
+            print(f"  - {tool.name}: {tool.description}")
+
+        # Get tools by name from the toolset
+        add_tool = find_tool(sse_toolset, "add")
+        if not add_tool:
+            print("Add tool not found!")
+            return
+
+        subtract_tool = find_tool(sse_toolset, "subtract")
+        if not subtract_tool:
+            print("Subtract tool not found!")
+            return
+
+        # Use the tools
+        result = add_tool.invoke(a=7, b=3)
+        print(f"7 + 3 = {result.content[0].text}")
+
+        result = subtract_tool.invoke(a=5, b=3)
+        print(f"5 - 3 = {result.content[0].text}")
+
+        result = add_tool.invoke(a=10, b=20)
+        print(f"10 + 20 = {result.content[0].text}")
+
+    except Exception as e:
+        print(f"Error in SSE toolset example: {e}")
+
+
+if __name__ == "__main__":
+    main()

integrations/mcp/examples/mcp_sse_toolset.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
+
+# This example shows how to use MCPToolset with stdio transport
+# MCPToolset automatically discovers all available tools from the MCP server
+# Here we use the mcp-server-time server
+# See https://github.com/modelcontextprotocol/servers/tree/main/src/time for more details
+# prior to running this script, pip install mcp-server-time
+
+
+def find_tool(toolset, tool_name):
+    """
+    Find a tool by name in the toolset.
+
+    :param toolset: The toolset to search in
+    :param tool_name: The name of the tool to find
+    :returns: The tool if found, None otherwise
+    """
+    for tool in toolset:
+        if tool.name == tool_name:
+            return tool
+    return None
+
+
+def main():
+    """Example of using the MCPToolset implementation with stdio transport."""
+
+    try:
+        # Create server info for the time service
+        server_info = StdioServerInfo(command="uvx", args=["mcp-server-time", "--local-timezone=Europe/Berlin"])
+
+        # Create the toolset - this will automatically discover all available tools
+        stdio_toolset = MCPToolset(server_info=server_info)
+
+        # Print discovered tools
+        print(f"Discovered {len(stdio_toolset)} tools:")
+        for tool in stdio_toolset:
+            print(f"  - {tool.name}: {tool.description}")
+
+        # Find tools by name using the helper function
+        time_tool = find_tool(stdio_toolset, "get_current_time")
+        if not time_tool:
+            print("Time tool not found!")
+            return
+
+        # Use the get_current_time tool
+        result = time_tool.invoke(timezone="America/New_York")
+        print(f"Current time in New York: {result.content[0].text}")
+
+        result = time_tool.invoke(timezone="America/Los_Angeles")
+        print(f"Current time in Los Angeles: {result.content[0].text}")
+    except Exception as e:
+        print(f"Error in stdio toolset example: {e}")
+
+
+if __name__ == "__main__":
+    main()