CrewAI MCP Tutorial: Give Your Crew Tools From Any MCP Server

CrewAI gives you two ways to plug MCP servers into agents. The simple way is the mcps field on an Agent, which takes URLs or config objects and discovers tools for you. The manual way is MCPServerAdapter from crewai-tools, which hands you a list of tools inside a context manager.

This tutorial builds a one-agent crew with the mcps field, adds a filtered local server, then shows the adapter pattern for crews built with @CrewBase. Code was checked against the CrewAI MCP docs on 2 November 2026, when crewai and crewai-tools 1.15.34 were current on PyPI.

Prerequisites

• Python 3.10 to 3.13 (crewai 1.15.34 declares >=3.10,<3.14).
• uv or pip, and an API key for the model your crew uses.
• Node.js if you want to run npx servers or the MCP Inspector.

Install

The docs show two installs, depending on the approach:

# For the mcps field (recommended)
uv add mcp

# For MCPServerAdapter
uv pip install 'crewai-tools[mcp]'

The version pin you need to know

On PyPI, crewai 1.15.34 requires mcp>=1.30.0,<2. That matters because the official Python SDK v2 and FastMCP 4 changed server imports. Old server code using from mcp.server.fastmcp import FastMCP still works in a CrewAI environment, but code written for v2 (from mcp.server import MCPServer) will not install alongside CrewAI.

The fix is simple: run your MCP server in its own virtual environment or container, and connect to it over HTTP or stdio. That is better practice anyway.

Minimal working example

Start any Streamable HTTP server on http://localhost:8000/mcp. The FastMCP notes server in our langchain-mcp-adapters tutorial works; run it in a separate environment as explained above. Then:

from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerHTTP

notes_agent = Agent(
    role="Notes Assistant",
    goal="Answer questions using the team's saved notes",
    backstory="You look things up in the notes server before answering.",
    mcps=[
        MCPServerHTTP(
            url="http://localhost:8000/mcp",
            streamable=True,
            cache_tools_list=True,
        ),
    ],
)

task = Task(
    description="List the saved notes and summarize the welcome note.",
    expected_output="A one-paragraph summary of the welcome note.",
    agent=notes_agent,
)

crew = Crew(agents=[notes_agent], tasks=[task])
print(crew.kickoff())

The docs say MCP tools "are automatically discovered and available to your agent." streamable=True is the default for MCPServerHTTP; it is shown here so you know where to switch it.

String references for quick setup

The mcps list also accepts plain strings:

mcps=[
    "https://mcp.example.com/api",                    # all tools from a remote server
    "https://api.weather.com/mcp#get_current_weather",  # one tool, using #
    "snowflake",                                      # a connected MCP from the CrewAI catalog
    "stripe#list_invoices",                           # one tool from a connected MCP
]

The #tool_name suffix is a quick way to expose a single tool. CrewAI's examples also show API keys in query strings, such as ?api_key=.... Prefer an Authorization header through MCPServerHTTP(headers=...) when the server supports it, so the key stays out of logs.

Add a local server and filter its tools

Here a filesystem server runs over stdio, and the agent only gets two tools:

from crewai import Agent
from crewai.mcp import MCPServerStdio
from crewai.mcp.filters import create_static_tool_filter

agent = Agent(
    role="File Reader",
    goal="Answer questions from project files",
    backstory="You read files but never change them.",
    mcps=[
        MCPServerStdio(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
            tool_filter=create_static_tool_filter(
                allowed_tool_names=["read_file", "list_directory"]
            ),
            cache_tools_list=True,
        ),
    ],
)

create_static_tool_filter takes allowed_tool_names and blocked_tool_names. There is also a dynamic option that decides per agent. The docs' example blocks any tool with "delete" in its name when the agent's role is "Code Reviewer":

from crewai.mcp.filters import ToolFilterContext


def dynamic_filter(context: ToolFilterContext, tool: dict) -> bool:
    if context.agent.role == "Code Reviewer":
        if "delete" in tool.get("name", "").lower():
            return False
    return True

Pass the function as tool_filter=dynamic_filter. Name-based rules like this are a backstop, not a guarantee; a tool called remove_file would slip through. Our filesystem server profile lists that server's write tools so you know what to block.

The adapter approach

Use MCPServerAdapter when you need to manage the connection yourself. A with block opens and closes it:

import os

from crewai import Agent
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="python3",
    args=["servers/your_server.py"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools:
    print([tool.name for tool in mcp_tools])
    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,
    )
    # build and kick off the crew inside the block

For HTTP, pass a dict instead: {"url": "http://localhost:8001/mcp", "transport": "streamable-http"}. You can pick one tool with mcp_tools["tool_name"], or pass tool names to the constructor after the params.

One caution: the adapter example passes **os.environ to the server process. That gives the server every secret in your shell. Pass only the variables it needs.

Inside a @CrewBase crew

Set mcp_server_params on the class and call self.get_mcp_tools():

@CrewBase
class CrewWithMCP:
    mcp_server_params = [
        {"url": "http://localhost:8001/mcp", "transport": "streamable-http"},
    ]
    mcp_connect_timeout = 60

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

The docs say @CrewBase creates one shared adapter on first use and shuts it down after .kickoff() completes, so you do not clean up by hand. get_mcp_tools("tool_1", "tool_2") limits an agent to named tools.

Add a tool

Tools come from the server, so you add them there. Add a function to your server, restart it, and the agent gets it on the next discovery. If you set cache_tools_list=True, restart the crew process too.

Test with the MCP Inspector

Check the server outside CrewAI first:

npx @modelcontextprotocol/inspector --cli http://localhost:8000/mcp --transport http --method tools/list

If tools show here but not in the crew, look at your filter and the agent's warnings. Our MCP Inspector lesson covers tool calls and scripted checks.

How failures behave

The docs say the mcps integration is "designed to be resilient":

• Connection failures are logged as warnings, and "agent continues with available tools."
• Connections time out after 30 seconds by default.
• Invalid configurations raise validation errors when the agent is created.

That is friendly in development and risky in production. A crew can quietly run without the tool it needs. Check the logs, or fail the run yourself if an expected tool is missing.

Security

CrewAI's MCP security page is blunt: "only connect your CrewAI agents to MCP servers that you fully trust." It warns that a malicious server can put instructions in tool names and descriptions, and that this "can occur simply by connecting to a malicious server and listing its tools." Read our tool poisoning guide and run new servers through the MCP server risk checklist before a crew touches them.

Pitfalls

• SSE by habit. MCPServerSSE exists for older servers. Use MCPServerHTTP for anything new.
• One crew, every tool. Give each agent its own filtered server list. A researcher does not need write tools.
• Mixing server and crew dependencies. Keep servers in separate environments because of the mcp<2 pin.

Next step

For the protocol basics behind all this, take the free MCP course. If you want MCP servers built for your crews, with scoped credentials and tested tool descriptions, see our MCP development service.

Frequently asked questions