Connect Tools and MCP Servers to CrewAI Agents

Give an agent working tools - custom Python, prebuilt crewai_tools, or MCP servers - without the 0.x-era mistakes that fail silently.

Verified against crewai 1.15.22 and 1.15.23 on 2026-10-01. Live-tested on CrewAI AMP and real LLMs on 2026-10-01. Run crewai version first; if the major/minor differs from 1.15, re-verify version-sensitive rows with the ask-docs skill before trusting them.

1. Pick the mechanism

mcp is already a core dependency of crewai 1.15.x - native mcps= needs no extra install.

2. Imports

from crewai.tools import BaseTool, tool, ToolFailure, ToolExecutionFailedError
from crewai.mcp import (
    MCPServerStdio, MCPServerHTTP, MCPServerSSE,
    create_static_tool_filter, create_dynamic_tool_filter,
)
from crewai.mcp.exceptions import MCPConnectionError

3. Custom tools

from pydantic import BaseModel, Field
from crewai.tools import BaseTool, tool

class PriceInput(BaseModel):
    sku: str = Field(..., description="Product SKU, e.g. 'A-100'")
    currency: str = Field("EUR", description="ISO currency code")

class PriceTool(BaseTool):
    name: str = "price_lookup"
    description: str = "Return the unit price for a SKU. Use before quoting a price."
    args_schema: type[BaseModel] = PriceInput

    def _run(self, sku: str, currency: str = "EUR") -> str:
        return f"{sku} costs 9.99 {currency}"

@tool("Unit Converter")
def convert(km: float) -> str:
    """Convert kilometres to miles."""
    return f"{km * 0.621371:.1f} mi"

print(PriceTool().run(sku="A-100"))   # args are validated against PriceInput first
print(convert.run(km=10))

Rules that prevent real failures:

Per-tool options (all on BaseTool and accepted by @tool(...) where noted):

Failures: a tool that raises does not fail the crew. The exception text is fed back to the agent and recorded as a tool failure, and the crew finishes "successfully". When downstream code must know, return ToolFailure(...) and set tool_failure_policy="raise", or inspect result.tasks_output[i].tool_failures. Full examples: references/custom-tools.md.

Task(tools=[...]) replaces the agent's tools for that task; it does not add to them.

4. Tool result caching

Through crewai 1.15.2 the crew cached tool results by default; from 1.15.3 it is opt-in. If you relied on the old behaviour, set Crew(cache=True) explicitly. Never enable it for live-data or state-changing tools unless their cache_function returns False.

A separate guard is not caching: if the agent repeats the exact same call twice in a row, crewai refuses the second call ("I tried reusing the same input...") whether or not caching is on.

5. crewai_tools: names that exist

crewai-tools 1.15.22-1.15.23 exports 118 names. Import a tool before you write code around it. Models routinely invent these:

Many tools need a third-party package. When it is missing, constructing the tool asks You are missing the '<pkg>' package. Would you like to install it? [y/N] (verified for EXASearchTool, TavilySearchTool, FirecrawlSearchTool, SeleniumScrapingTool). With a terminal attached that blocks forever; with stdin closed it raises click.exceptions.Abort. Install the extra up front, e.g. uv add "crewai-tools[exa-py]". Prebuilt tools are offered to the LLM under their sanitized display name, not the class name: DirectoryReadTool appears as list_files_in_directory, FileReadTool as read_a_files_content. RAG tools (WebsiteSearchTool, PDFSearchTool, ...) fail at construction without an embedder key. Full list and extras: references/crewai-tools-names.md.

6. Native Agent(mcps=[...])

from crewai import Agent
from crewai.mcp import MCPServerHTTP, MCPServerSSE, MCPServerStdio, create_static_tool_filter

agent = Agent(
    role="Inventory analyst",
    goal="Answer stock questions",
    backstory="Careful with numbers.",
    mcps=[
        MCPServerHTTP(url="https://mcp.example.com/mcp",
                      headers={"Authorization": "Bearer <your-key>"}),
        MCPServerSSE(url="https://legacy.example.com/sse"),
        MCPServerStdio(command="uvx", args=["mcp-server-time"],
                       tool_filter=create_static_tool_filter(allowed_tool_names=["get_current_time"])),
        "https://docs.example.com/mcp#search_docs",   # https string, one tool (sync kickoff only - section 8)
        "acme#lookup_stock",                           # AMP-connected integration, one tool
        "acme#list_warehouses",                        # second tool = second ref
    ],
)

String refs are validated at construction; nothing connects until a task runs.

Full examples for each transport, dynamic filters and the AMP form: references/mcp-connections.md.

7. MCP tool names are rewritten - never hard-code them

Native MCP tools are offered to the LLM as <server name>_<tool name>, then sanitized: lowercase, non-alphanumerics become _, camelCase is split, max 64 characters.

Consequences:

• Do not write "call the lookup_stock tool" in a task description or backstory. Describe the capability ("check stock levels with the inventory tool"), or derive the exact name at runtime. A native function-calling model usually copes (claude-haiku-4-5 told "call the lookup_stock tool" called python_mcp_server_py_lookup_stock), but a model on the text ReAct path fails with Action 'lookup_stock' don't exist, and a hashed name leaves only the description to go on.
• Keep stdio command/args short ("uvx", "npx", a relative script path) so names stay readable and under 64 characters. Absolute paths also put your filesystem layout into every prompt. A scoped npx package already uses about 45 characters: npx -y @modelcontextprotocol/server-filesystem ./data hashed list_allowed_directories to ..._data_list_4ab656ee; use MCPServerAdapter when bare names matter.
• In code, identify a resolved native MCP tool by tool.original_tool_name, not by tool.name.

8. Timeouts, retries and failure behaviour

In 1.15.22-1.15.23 the native timeouts are module constants. No field on MCPServerStdio, MCPServerHTTP, MCPServerSSE or Agent changes them. So:

• Keep MCP tool calls well under 30 s. Make them idempotent, because a timed-out call is re-sent. For long jobs, return a job id from one tool and poll with another.
• Prefer config objects to https:// strings in production: they fail loudly at kickoff instead of silently dropping tools.
• https:// strings discover tools with asyncio.run(). Inside a running event loop that fails and the agent gets zero tools with no error (only RuntimeWarning: coroutine 'MCPToolResolver._get_mcp_tool_schemas_async' was never awaited). Seen live with await crew.akickoff() and on a CrewAI AMP deployment - the agent runs without the tools, and its answer may describe tool calls it never made. The same server as MCPServerHTTP(url=...) worked in both places. Sync crew.kickoff(), including from a sync Flow step, resolves strings fine.
• An MCP result with isError: true reaches the agent as text. It is recorded as a mcp_error tool failure, and tool_failure_policy="raise" turns it into ToolExecutionFailedError.

9. MCPServerAdapter and @CrewBase mcp_server_params

MCPServerAdapter needs the extra: uv add "crewai-tools[mcp]" (it installs mcpadapt; mcp itself is already present). Without the extra, constructing it asks You are missing the 'mcp' package. Would you like to install it? [y/N]. Under a terminal that blocks forever; with stdin closed (typical CI) it raises click.exceptions.Abort. Install the extra explicitly.

from mcp import StdioServerParameters
from crewai_tools import MCPServerAdapter

params = StdioServerParameters(command="python", args=["mcp_server.py"])
with MCPServerAdapter(params, "lookup_stock", connect_timeout=60) as tools:
    print([t.name for t in tools])   # ['lookup_stock'] - bare names, filtered by name
    # build agents with tools=tools and kick off INSIDE the with-block

The server starts in the constructor and stops when the with block exits. Tools used after that fail. For a remote server pass a dict and name the transport: {"url": "https://<host>/mcp", "transport": "streamable-http"}. Without "transport" the adapter speaks SSE, and against a streamable-HTTP /mcp endpoint it fails with Couldn't connect to the MCP server after <connect_timeout> seconds.

In a @CrewBase class, set mcp_server_params (and optionally mcp_connect_timeout, default 30) and call self.get_mcp_tools("name", ...) in an @agent method. crewai stops that adapter after every kickoff. Calling .crew().kickoff() a second time on the same instance made every MCP call return Event loop is closed, yet the crew still "succeeded". Build a fresh instance per run: InventoryCrew().crew().kickoff().

10. Hosted deployments: what works on CrewAI AMP

Measured on a CrewAI AMP deployment (ZIP deploy, crewai 1.15.23, anthropic/claude-haiku-4-5), one kickoff per form:

How a failed MCP connection looks from the API: for each MCPConnectionError run above, GET /status/{kickoff_id} answered HTTP 500 Internal Server Error (plain text) on every poll, minutes later too, instead of a JSON FAILED state. A plain exception in the same crew gave the documented shape: {"state": "FAILED", "status": "ValueError: ..."}. Treat a persistent 500 from /status as "the run failed", and check the MCP connection first.

Rules:

• A stdio server runs as a child process wherever the crew runs. Ship it inside the package (src/<pkg>/server.py, started with python -m <pkg>.server) and its Python dependencies in pyproject.toml/uv.lock; a laptop path or a Node/npx server is not there.
• For remote servers use MCPServerHTTP(url="https://<host>/mcp") (or MCPServerSSE), never an https:// string. Point deployments at a stable hostname you control, require auth on it, and do not leave temporary tunnels running.
• Health check: a bare curl -s -o /dev/null -w "%{http_code}" https://<host>/mcp returns 406 from a healthy streamable-HTTP MCP endpoint (seen on a public server and locally). 404 means wrong path; 000/connection refused means it is down.
• Put tokens in headers read from environment variables (os.environ["ACME_MCP_TOKEN"]), never in the URL string or in code. A stdio server gets deployment env vars only through env=.

Common mistakes

Checklist

• BaseTool/tool imported from crewai.tools; every crewai_tools name imported once to prove it exists
• Custom tools define _run, have an args_schema (or typed @tool signature) and an LLM-oriented description
• Failures returned as ToolFailure; tool_failure_policy chosen deliberately
• Crew(cache=...) set explicitly; live-data tools excluded from caching
• Optional packages and crewai-tools[mcp] installed up front, so no interactive prompt can block
• One "slug#tool" ref per tool; http:// servers via MCPServerHTTP, not a string; hostnames, not IP addresses
• No https:// string refs in deployed crews or with akickoff() - use MCPServerHTTP
• No prompt or code depends on a bare MCP tool name; stdio commands kept short
• stdio servers get their keys through env= (they do not inherit the crew's environment)
• MCP tool calls finish well under 30 s and are idempotent
• Deployed crews use HTTP/SSE MCP servers at a stable URL that returns 406 on a bare GET, or stdio servers shipped inside the package
• A fresh @CrewBase instance per kickoff when using mcp_server_params

References

• Custom Tools - BaseTool, @tool, async, ToolFailure and failure policy, caching, usage limits, with runnable examples
• MCP Connections - every mcps= form, filters, name derivation, timeouts, MCPServerAdapter, @CrewBase, deployment
• crewai_tools Names - the full 1.15.22-1.15.23 export list, hallucinated names, extras and construction behaviour
• Public docs: https://docs.crewai.com/en/concepts/tools and https://docs.crewai.com/en/mcp/overview

For related skills:

• check-crewai-api - current Agent/Task/Crew API and imports beyond tools
• design-agent - choosing how many tools an agent gets and writing role/goal/backstory
• test-crewai-project - driving tool calls offline with a stub LLM
• deploy-to-amp - getting a project with MCP connections onto CrewAI AMP
• ask-docs - query the live docs when the installed version differs