​
Overview

The Model Context Protocol (MCP) provides a standardized way for AI agents to provide context to LLMs by communicating with external services, known as MCP Servers. The crewai-tools library extends CrewAI’s capabilities by allowing you to seamlessly integrate tools from these MCP servers into your agents. This gives your crews access to a vast ecosystem of functionalities. We currently support the following transport mechanisms:
  • Stdio: for local servers (communication via standard input/output between processes on the same machine)
  • Server-Sent Events (SSE): for remote servers (unidirectional, real-time data streaming from server to client over HTTP)
  • Streamable HTTP: for remote servers (flexible, potentially bi-directional communication over HTTP, often utilizing SSE for server-to-client streams)

​
Video Tutorial

Watch this video tutorial for a comprehensive guide on MCP integration with CrewAI:

​
Installation

Before you start using MCP with crewai-tools, you need to install the mcp extra crewai-tools dependency with the following command: 
uv pip install 'crewai-tools[mcp]'

​
Key Concepts & Getting Started

The MCPServerAdapter class from crewai-tools is the primary way to connect to an MCP server and make its tools available to your CrewAI agents. It supports different transport mechanisms and simplifies connection management. Using a Python context manager (with statement) is the recommended approach for MCPServerAdapter. It automatically handles starting and stopping the connection to the MCP server.

​
Connection Configuration

The MCPServerAdapter supports several configuration options to customize the connection behavior:
  • connect_timeout (optional): Maximum time in seconds to wait for establishing a connection to the MCP server. Defaults to 30 seconds if not specified. This is particularly useful for remote servers that may have variable response times.
# Example with custom connection timeout
with MCPServerAdapter(server_params, connect_timeout=60) as tools:
    # Connection will timeout after 60 seconds if not established
    pass

from crewai import Agent
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters # For Stdio Server

# Example server_params (choose one based on your server type):
# 1. Stdio Server:
server_params=StdioServerParameters(
    command="python3",
    args=["servers/your_server.py"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

# 2. SSE Server:
server_params = {
    "url": "http://localhost:8000/sse",
    "transport": "sse"
}

# 3. Streamable HTTP Server:
server_params = {
    "url": "http://localhost:8001/mcp",
    "transport": "streamable-http"
}

# Example usage (uncomment and adapt once server_params is set):
with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools:
    print(f"Available tools: {[tool.name for tool in mcp_tools]}")

    my_agent = Agent(
        role="MCP Tool User",
        goal="Utilize tools from an MCP server.",
        backstory="I can connect to MCP servers and use their tools.",
        tools=mcp_tools, # Pass the loaded tools to your agent
        reasoning=True,
        verbose=True
    )
    # ... rest of your crew setup ...
This general pattern shows how to integrate tools. For specific examples tailored to each transport, refer to the detailed guides below.

​
Filtering Tools

There are two ways to filter tools:
  1. Accessing a specific tool using dictionary-style indexing.
  2. Pass a list of tool names to the MCPServerAdapter constructor.

​
Accessing a specific tool using dictionary-style indexing.

with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools:
    print(f"Available tools: {[tool.name for tool in mcp_tools]}")

    my_agent = Agent(
        role="MCP Tool User",
        goal="Utilize tools from an MCP server.",
        backstory="I can connect to MCP servers and use their tools.",
        tools=[mcp_tools["tool_name"]], # Pass the loaded tools to your agent
        reasoning=True,
        verbose=True
    )
    # ... rest of your crew setup ...

​
Pass a list of tool names to the MCPServerAdapter constructor.

with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) as mcp_tools:
    print(f"Available tools: {[tool.name for tool in mcp_tools]}")

    my_agent = Agent(
        role="MCP Tool User",
        goal="Utilize tools from an MCP server.",
        backstory="I can connect to MCP servers and use their tools.",
        tools=mcp_tools, # Pass the loaded tools to your agent
        reasoning=True,
        verbose=True
    )
    # ... rest of your crew setup ...

​
Using with CrewBase

To use MCPServer tools within a CrewBase class, use the get_mcp_tools method. Server configurations should be provided via the mcp_server_params attribute. You can pass either a single configuration or a list of multiple server configurations. 
@CrewBase
class CrewWithMCP:
  # ... define your agents and tasks config file ...

  mcp_server_params = [
    # Streamable HTTP Server
    {
        "url": "http://localhost:8001/mcp",
        "transport": "streamable-http"
    },
    # SSE Server
    {
        "url": "http://localhost:8000/sse",
        "transport": "sse"
    },
    # StdIO Server
    StdioServerParameters(
        command="python3",
        args=["servers/your_stdio_server.py"],
        env={"UV_PYTHON": "3.12", **os.environ},
    )
  ]

  @agent
  def your_agent(self):
      return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # get all available tools

    # ... rest of your crew setup ...

​
Connection Timeout Configuration

You can configure the connection timeout for MCP servers by setting the mcp_connect_timeout class attribute. If no timeout is specified, it defaults to 30 seconds. 
@CrewBase
class CrewWithMCP:
  mcp_server_params = [...]
  mcp_connect_timeout = 60  # 60 seconds timeout for all MCP connections

  @agent
  def your_agent(self):
      return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools())

@CrewBase
class CrewWithDefaultTimeout:
  mcp_server_params = [...]
  # No mcp_connect_timeout specified - uses default 30 seconds

  @agent
  def your_agent(self):
      return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools())

​
Filtering Tools

You can filter which tools are available to your agent by passing a list of tool names to the get_mcp_tools method. 
@agent
def another_agent(self):
    return Agent(
      config=self.agents_config["your_agent"],
      tools=self.get_mcp_tools("tool_1", "tool_2") # get specific tools
    )
The timeout configuration applies to all MCP tool calls within the crew: 
@CrewBase
class CrewWithCustomTimeout:
  mcp_server_params = [...]
  mcp_connect_timeout = 90  # 90 seconds timeout for all MCP connections

  @agent
  def filtered_agent(self):
      return Agent(
        config=self.agents_config["your_agent"],
        tools=self.get_mcp_tools("tool_1", "tool_2") # specific tools with custom timeout
      )

​
Explore MCP Integrations

Stdio Transport

Connect to local MCP servers via standard input/output. Ideal for scripts and local executables.

SSE Transport

Integrate with remote MCP servers using Server-Sent Events for real-time data streaming.

Streamable HTTP Transport

Utilize flexible Streamable HTTP for robust communication with remote MCP servers.

Connecting to Multiple Servers

Aggregate tools from several MCP servers simultaneously using a single adapter.

Security Considerations

Review important security best practices for MCP integration to keep your agents safe.
Checkout this repository for full demos and examples of MCP integration with CrewAI! 👇

GitHub Repository

CrewAI MCP Demo

​
Staying Safe with MCP

Always ensure that you trust an MCP Server before using it.

​
Security Warning: DNS Rebinding Attacks

SSE transports can be vulnerable to DNS rebinding attacks if not properly secured. To prevent this:
  1. Always validate Origin headers on incoming SSE connections to ensure they come from expected sources
  2. Avoid binding servers to all network interfaces (0.0.0.0) when running locally - bind only to localhost (127.0.0.1) instead
  3. Implement proper authentication for all SSE connections
Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites. For more details, see the Anthropic’s MCP Transport Security docs.

​
Limitations

  • Supported Primitives: Currently, MCPServerAdapter primarily supports adapting MCP tools. Other MCP primitives like prompts or resources are not directly integrated as CrewAI components through this adapter at this time.
  • Output Handling: The adapter typically processes the primary text output from an MCP tool (e.g., .content[0].text). Complex or multi-modal outputs might require custom handling if not fitting this pattern.