MCP server CrewAI integration

CrewAI architecture and where MCP fits

A CrewAI application has four core building blocks:

MCP servers are external infrastructure — they sit behind the tool interface and implement the actual work. The MCP server doesn't know it's being called by CrewAI; CrewAI doesn't know (or care) how the tool is implemented. This separation lets you update, replace, or scale MCP servers independently of your crew configuration.

Installing and connecting with MCPServerAdapter

CrewAI's MCP integration requires crewai[tools] >= 0.105:

pip install "crewai[tools]>=0.105" langchain-anthropic
# or with uv:
uv add "crewai[tools]>=0.105" langchain-anthropic

Connect to an MCP server using MCPServerAdapter:

import asyncio
import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters

async def run_research_crew():
    # HTTP/SSE MCP server
    search_params = {
        "url": "https://search.internal/mcp",
        "transport": "streamable_http",
        "headers": {"Authorization": f"Bearer {os.environ['SEARCH_TOKEN']}"},
    }

    # Stdio MCP server (local package)
    calculator_params = StdioServerParameters(
        command="npx",
        args=["-y", "@acme/calculator-mcp"],
    )

    async with MCPServerAdapter(search_params) as search_adapter, \
               MCPServerAdapter(calculator_params) as calc_adapter:

        researcher = Agent(
            role="Research Analyst",
            goal="Find and summarise the most relevant information on the given topic",
            backstory="Expert at web research and source evaluation",
            tools=search_adapter.tools,  # only search tools
            llm="claude-sonnet-4-6",
            verbose=False,
        )

        analyst = Agent(
            role="Data Analyst",
            goal="Compute metrics and validate numbers from research output",
            backstory="Expert at quantitative analysis and statistical validation",
            tools=calc_adapter.tools,  # only calculator tools
            llm="claude-sonnet-4-6",
            verbose=False,
        )

        research_task = Task(
            description="Research the current state of MCP server adoption in enterprise environments",
            expected_output="A structured summary with key statistics and adoption trends",
            agent=researcher,
        )

        analysis_task = Task(
            description="Validate the statistics from the research and compute year-over-year growth rates",
            expected_output="A validated metrics table with growth calculations",
            agent=analyst,
            context=[research_task],  # receives researcher output
        )

        crew = Crew(
            agents=[researcher, analyst],
            tasks=[research_task, analysis_task],
            process=Process.sequential,
        )

        result = await crew.kickoff_async()
        return result.raw

asyncio.run(run_research_crew())

Role-based tool assignment

The most common mistake in CrewAI + MCP integration is giving every agent all available tools. An agent given 20 tools performs worse than one given the 3–5 tools it actually needs: LLMs degrade in tool selection accuracy as the tool count grows, and unrelated tools introduce noise in the agent's reasoning about which tool to call next.

Assign tools by role — each MCP server provides tools for one domain, and those tools go to the agent whose role is in that domain:

In a Process.hierarchical crew, the manager agent coordinates without executing tasks directly. Give the manager no tools or a minimal set (e.g., a delegate tool) and concentrate capabilities in the worker agents.

Sequential vs hierarchical process

CrewAI's Process.sequential runs tasks one after another — each task's output becomes available as context to subsequent tasks. Process.hierarchical adds a manager LLM that dynamically assigns tasks to agents based on the crew's progress. Both patterns work with MCP tools:

# Sequential: tasks run in order, researcher output feeds analyst
crew_sequential = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
)

# Hierarchical: manager decides which agent to use next
crew_hierarchical = Crew(
    agents=[researcher, analyst, writer],
    tasks=[project_task],  # single high-level task; manager decomposes it
    process=Process.hierarchical,
    manager_llm="claude-opus-4-7",  # use a stronger model as manager
)

In hierarchical mode, the manager LLM's context grows with each subtask delegation. Keep individual task descriptions concise so the manager prompt stays within the model's context window over a long-running crew execution.

Batch scheduling and pre-flight health checks

CrewAI is often used for scheduled batch workflows: nightly research reports, weekly competitive analysis, daily data summaries. These run unattended, which means a dead MCP server at job startup fails silently — the crew kickoff raises a connection error that lands in a log file nobody checks until the morning report is missing.

import httpx
from datetime import datetime

async def preflight_check(servers: list[dict]) -> None:
    """Verify all MCP servers are reachable before starting an expensive crew run."""
    async with httpx.AsyncClient(timeout=5.0) as http:
        for server in servers:
            try:
                resp = await http.post(
                    server["url"],
                    json={"jsonrpc": "2.0", "method": "initialize",
                          "params": {"protocolVersion": "2025-03-26", "capabilities": {},
                                     "clientInfo": {"name": "preflight", "version": "1"}}, "id": 1},
                    headers=server.get("headers", {}),
                )
                if resp.status_code != 200:
                    raise RuntimeError(
                        f"MCP server {server['url']} returned HTTP {resp.status_code} — aborting crew run"
                    )
            except httpx.ConnectError as exc:
                raise RuntimeError(f"Cannot reach MCP server {server['url']}: {exc}") from exc

async def run_nightly_crew():
    await preflight_check([
        {"url": "https://search.internal/mcp", "headers": {"Authorization": f"Bearer {os.environ['SEARCH_TOKEN']}"}},
        {"url": "https://db.internal/mcp", "headers": {"Authorization": f"Bearer {os.environ['DB_TOKEN']}"}},
    ])
    # only proceed if all servers passed
    async with MCPServerAdapter(...) as adapter:
        ...

For production deployments, delegate the pre-flight monitoring to AliveMCP — it runs continuous probes every minute and alerts when any server goes down, not just at job start time. Your batch job can then check AliveMCP's status API instead of running raw MCP probes inline.

Error handling in CrewAI with MCP tools

When an MCP tool returns isError: true, MCPServerAdapter raises a ToolException. CrewAI's agent executor injects the error message back into the conversation. The agent's LLM sees the error and typically retries with different arguments or uses a different approach.

Configure max_iter on the agent to cap retry loops:

researcher = Agent(
    role="Research Analyst",
    goal="...",
    backstory="...",
    tools=search_adapter.tools,
    llm="claude-sonnet-4-6",
    max_iter=5,       # stop after 5 tool call iterations
    max_retry_limit=2,  # retry failed tool calls up to 2 times
)

Without max_iter, an agent that gets consistent MCP errors can loop indefinitely, consuming tokens until the context window fills. Five iterations is a reasonable ceiling for most research tasks; reduce to 3 for tools with high per-call cost.

Monitoring MCP servers that power CrewAI

CrewAI is particularly vulnerable to MCP server failures in two scenarios. First, scheduled batch jobs: the crew runs at a fixed time, the MCP server is down, the job logs an error and exits — no alert fires, no human notices, the morning report is missing. Second, long-running crews: a crew running for 20 minutes completes 15 of 20 tasks successfully, then fails at task 16 because the MCP server restarted — all prior work is discarded unless the crew supports partial output recovery.

AliveMCP monitors each MCP server endpoint independently, 24/7, and sends alerts the moment a server fails — not when the next scheduled job discovers the failure. Configure one AliveMCP monitor per MCP server with a webhook alert that fires to your on-call channel. Your crew's reliability is now bounded by the reliability of its MCP servers; AliveMCP makes that boundary visible.

Further reading

• MCP server LangChain integration — using MCP tools in LangChain agents
• MCP server LangGraph integration — stateful agents with MCP tools
• MCP server AutoGen integration — Microsoft AutoGen with MCP tools
• MCP server authentication — OAuth, JWT, and API key patterns
• MCP server alerting — notifications when your server goes down
• AliveMCP — continuous protocol monitoring for MCP servers