# MCP Haystack Integration
This integration adds support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) to Haystack. MCP is an open protocol that standardizes how applications provide context to LLMs, similar to how USB-C provides a standardized way to connect devices.
## Installation
```bash
pip install mcp-haystack
```
## Usage
### Using Individual Tools (MCPTool)
```python
from haystack_integrations.tools.mcp import MCPTool, SSEServerInfo
# Create an MCP tool that connects to an HTTP server
server_info = SSEServerInfo(url="http://localhost:8000/sse")
tool = MCPTool(name="my_tool", server_info=server_info)
# Use the tool
result = tool.invoke(param1="value1", param2="value2")
```
### Using Tool Collections (MCPToolset)
```python
from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo
# Create a toolset that automatically discovers all available tools
server_info = StdioServerInfo(command="uvx", args=["mcp-server-time"])
toolset = MCPToolset(server_info)
# Use tools from the toolset
for tool in toolset:
print(f"Available tool: {tool.name} - {tool.description}")
# Or filter to specific tools
filtered_toolset = MCPToolset(server_info, tool_names=["get_current_time"])
```
# Examples
Check out the examples directory to see practical demonstrations of how to integrate the MCPTool into Haystack's tooling architecture. These examples will help you get started quickly with your own agentic applications.
## What is uvx?
In some examples below, we use the `StdioServerInfo` class which relies on `uvx` behind the scenes. `uvx` is a convenient command from the uv package that runs Python tools in temporary, isolated environments. You only need to install `uvx` once, and it will automatically fetch any required packages on first use without needing manual installation.
## Example 1: MCP Server with SSE Transport
This example demonstrates how to create a simple calculator server using MCP and connect to it using MCPTool with SSE transport.
### Step 1: Run the MCP Server
First, run the server that exposes calculator functionality (addition and subtraction) via MCP:
```bash
python examples/mcp_server.py --transport sse
```
This creates a FastMCP server with two tools:
- `add(a, b)`: Adds two numbers
- `subtract(a, b)`: Subtracts two numbers
The server runs on http://localhost:8000 by default.
### Step 2: Connect with Individual Tools (MCPTool)
In a separate terminal, run the client that connects to the calculator server using individual MCPTool instances:
```bash
python examples/mcp_client.py --transport sse
```
The client creates MCPTool instances that connect to the server, inspect the tool specifications, and invoke the calculator functions remotely.
### Step 3: Connect with Tool Collections (MCPToolset)
Alternatively, use MCPToolset to automatically discover and use all available tools:
```bash
python examples/mcp_sse_toolset.py
```
This demonstrates how MCPToolset can automatically discover all tools from the server and create a collection of tools for easy access.
## Example 2: MCP with StdIO Transport
This example shows how to use MCP tools with stdio transport to execute a local program directly.
### Using Individual Tools (MCPTool)
```bash
python examples/mcp_stdio_client.py
```
The example creates an MCPTool that uses stdio transport with `StdioServerInfo`, which automatically uses `uvx` behind the scenes to run the `mcp-server-time` tool without requiring manual installation. It queries the current time in different timezones (New York and Los Angeles) by invoking the tool with different parameters.
### Using Tool Collections (MCPToolset)
```bash
python examples/mcp_stdio_toolset.py
```
This example demonstrates how MCPToolset can automatically discover all available tools from a stdio-based MCP server and create a collection for easy access.
Both approaches demonstrate how MCP tools can work with local programs without running a separate server process, using standard input/output for communication.
## Example 3: MCP Tools in Haystack Pipelines
These examples showcase how to integrate MCP tools into Haystack pipelines along with LLMs.
### Using Individual Tools (MCPTool)
```bash
python examples/time_pipeline.py
```
This example creates a pipeline that:
1. Takes a user query about the current time in a city
2. Uses an LLM (GPT-4o-mini) to interpret the query and decide which tool to use
3. Invokes the time tool with the appropriate parameters (using `uvx` behind the scenes)
4. Sends the tool's response back to the LLM to generate a final answer
### Using Tool Collections (MCPToolset)
```bash
python examples/time_pipeline_toolset.py
```
This example demonstrates the same functionality but uses MCPToolset instead of individual MCPTool instances. The toolset automatically discovers all available tools from the MCP server and makes them available to the LLM.
Both examples demonstrate how MCP tools can be seamlessly integrated into Haystack's agentic architecture, allowing LLMs to use external tools via the Model Context Protocol.
## Example 4: Advanced MCPToolset Features
### Tool Filtering
```bash
python examples/mcp_filtered_tools.py
```
This example demonstrates how to use MCPToolset with tool filtering, allowing you to selectively include only specific tools from an MCP server. This is useful when you want to limit which tools are available to your application or LLM.
## License
Apache 2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-haystack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Haystack, MCP, Model Context Protocol",
"author": null,
"author_email": "deepset GmbH <info@deepset.ai>",
"download_url": "https://files.pythonhosted.org/packages/94/6f/39a04ed7807fa423c5d24dd6209440be20780f939cee05ad510993f86dbb/mcp_haystack-0.5.0.tar.gz",
"platform": null,
"description": "# MCP Haystack Integration\n\nThis integration adds support for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) to Haystack. MCP is an open protocol that standardizes how applications provide context to LLMs, similar to how USB-C provides a standardized way to connect devices.\n\n## Installation\n\n```bash\npip install mcp-haystack\n```\n\n## Usage\n\n### Using Individual Tools (MCPTool)\n\n```python\nfrom haystack_integrations.tools.mcp import MCPTool, SSEServerInfo\n\n# Create an MCP tool that connects to an HTTP server\nserver_info = SSEServerInfo(url=\"http://localhost:8000/sse\")\ntool = MCPTool(name=\"my_tool\", server_info=server_info)\n\n# Use the tool\nresult = tool.invoke(param1=\"value1\", param2=\"value2\")\n```\n\n### Using Tool Collections (MCPToolset)\n\n```python\nfrom haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo\n\n# Create a toolset that automatically discovers all available tools\nserver_info = StdioServerInfo(command=\"uvx\", args=[\"mcp-server-time\"])\ntoolset = MCPToolset(server_info)\n\n# Use tools from the toolset\nfor tool in toolset:\n print(f\"Available tool: {tool.name} - {tool.description}\")\n\n# Or filter to specific tools\nfiltered_toolset = MCPToolset(server_info, tool_names=[\"get_current_time\"])\n```\n\n# Examples\n\nCheck out the examples directory to see practical demonstrations of how to integrate the MCPTool into Haystack's tooling architecture. These examples will help you get started quickly with your own agentic applications.\n\n## What is uvx?\n\nIn some examples below, we use the `StdioServerInfo` class which relies on `uvx` behind the scenes. `uvx` is a convenient command from the uv package that runs Python tools in temporary, isolated environments. You only need to install `uvx` once, and it will automatically fetch any required packages on first use without needing manual installation.\n\n## Example 1: MCP Server with SSE Transport\n\nThis example demonstrates how to create a simple calculator server using MCP and connect to it using MCPTool with SSE transport.\n\n### Step 1: Run the MCP Server\n\nFirst, run the server that exposes calculator functionality (addition and subtraction) via MCP:\n\n```bash\npython examples/mcp_server.py --transport sse\n```\n\nThis creates a FastMCP server with two tools:\n- `add(a, b)`: Adds two numbers\n- `subtract(a, b)`: Subtracts two numbers\n\nThe server runs on http://localhost:8000 by default.\n\n### Step 2: Connect with Individual Tools (MCPTool)\n\nIn a separate terminal, run the client that connects to the calculator server using individual MCPTool instances:\n\n```bash\npython examples/mcp_client.py --transport sse\n```\n\nThe client creates MCPTool instances that connect to the server, inspect the tool specifications, and invoke the calculator functions remotely.\n\n### Step 3: Connect with Tool Collections (MCPToolset)\n\nAlternatively, use MCPToolset to automatically discover and use all available tools:\n\n```bash\npython examples/mcp_sse_toolset.py\n```\n\nThis demonstrates how MCPToolset can automatically discover all tools from the server and create a collection of tools for easy access.\n\n## Example 2: MCP with StdIO Transport\n\nThis example shows how to use MCP tools with stdio transport to execute a local program directly.\n\n### Using Individual Tools (MCPTool)\n\n```bash\npython examples/mcp_stdio_client.py\n```\n\nThe example creates an MCPTool that uses stdio transport with `StdioServerInfo`, which automatically uses `uvx` behind the scenes to run the `mcp-server-time` tool without requiring manual installation. It queries the current time in different timezones (New York and Los Angeles) by invoking the tool with different parameters.\n\n### Using Tool Collections (MCPToolset)\n\n```bash\npython examples/mcp_stdio_toolset.py\n```\n\nThis example demonstrates how MCPToolset can automatically discover all available tools from a stdio-based MCP server and create a collection for easy access.\n\nBoth approaches demonstrate how MCP tools can work with local programs without running a separate server process, using standard input/output for communication.\n\n## Example 3: MCP Tools in Haystack Pipelines\n\nThese examples showcase how to integrate MCP tools into Haystack pipelines along with LLMs.\n\n### Using Individual Tools (MCPTool)\n\n```bash\npython examples/time_pipeline.py\n```\n\nThis example creates a pipeline that:\n1. Takes a user query about the current time in a city\n2. Uses an LLM (GPT-4o-mini) to interpret the query and decide which tool to use\n3. Invokes the time tool with the appropriate parameters (using `uvx` behind the scenes)\n4. Sends the tool's response back to the LLM to generate a final answer\n\n### Using Tool Collections (MCPToolset)\n\n```bash\npython examples/time_pipeline_toolset.py\n```\n\nThis example demonstrates the same functionality but uses MCPToolset instead of individual MCPTool instances. The toolset automatically discovers all available tools from the MCP server and makes them available to the LLM.\n\nBoth examples demonstrate how MCP tools can be seamlessly integrated into Haystack's agentic architecture, allowing LLMs to use external tools via the Model Context Protocol.\n\n## Example 4: Advanced MCPToolset Features\n\n### Tool Filtering\n\n```bash\npython examples/mcp_filtered_tools.py\n```\n\nThis example demonstrates how to use MCPToolset with tool filtering, allowing you to selectively include only specific tools from an MCP server. This is useful when you want to limit which tools are available to your application or LLM.\n\n## License\n\nApache 2.0 \n",
"bugtrack_url": null,
"license": null,
"summary": "Haystack integration for Model Context Protocol (MCP)",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mcp#readme",
"Issues": "https://github.com/deepset-ai/haystack-core-integrations/issues",
"Source": "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mcp"
},
"split_keywords": [
"haystack",
" mcp",
" model context protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f204d0939df1d9472fdf1041685d64666230e0a37b5c71a7b38c3eac062071a7",
"md5": "7b34b4a7e0f02b75cd8f35366cab5de9",
"sha256": "ea8117419ea379718156ebd593d28fe7671b27865b702b5c81034d9bfa9a37a9"
},
"downloads": -1,
"filename": "mcp_haystack-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b34b4a7e0f02b75cd8f35366cab5de9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22201,
"upload_time": "2025-08-04T09:41:26",
"upload_time_iso_8601": "2025-08-04T09:41:26.128533Z",
"url": "https://files.pythonhosted.org/packages/f2/04/d0939df1d9472fdf1041685d64666230e0a37b5c71a7b38c3eac062071a7/mcp_haystack-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "946f39a04ed7807fa423c5d24dd6209440be20780f939cee05ad510993f86dbb",
"md5": "94b41ac870bd399bc592f87a85427625",
"sha256": "0af5495c2e2d3a7968f60b0c420c6b5fbdc2b2a308d76abab32e72b3dec1c74f"
},
"downloads": -1,
"filename": "mcp_haystack-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "94b41ac870bd399bc592f87a85427625",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 36164,
"upload_time": "2025-08-04T09:41:27",
"upload_time_iso_8601": "2025-08-04T09:41:27.148470Z",
"url": "https://files.pythonhosted.org/packages/94/6f/39a04ed7807fa423c5d24dd6209440be20780f939cee05ad510993f86dbb/mcp_haystack-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 09:41:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepset-ai",
"github_project": "haystack-core-integrations",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "hatch",
"specs": []
}
],
"lcname": "mcp-haystack"
}
JSON
