crewAIInc/crewAI · error · RuntimeError

Failed to initialize MCP Adapter: {e}

Error message

Failed to initialize MCP Adapter: {e}

What it means

Raised when MCPServerAdapt's __init__ fails while constructing or starting the underlying MCPAdapt adapter. The constructor wraps any exception (bad server params, connection failure, mcp-adapt internal error, invalid tool config) into a RuntimeError with the original cause chained via `from e`. Any non-None adapter is stopped before raising so no orphan process is left.

Source

Thrown at lib/crewai-tools/src/crewai_tools/adapters/mcp_adapter.py:190

            else:
                raise ImportError(
                    "`mcp` package not found, please run `uv add crewai-tools[mcp]`"
                )

        try:
            self._serverparams = serverparams
            self._adapter = MCPAdapt(
                self._serverparams, CrewAIToolAdapter(), connect_timeout
            )
            self.start()

        except Exception as e:
            if self._adapter is not None:
                try:
                    self.stop()
                except Exception as stop_e:
                    logger.error(f"Error during stop cleanup: {stop_e}")
            raise RuntimeError(f"Failed to initialize MCP Adapter: {e}") from e

    def start(self) -> None:
        """Start the MCP server and initialize the tools."""
        self._tools = self._adapter.__enter__()  # type: ignore[union-attr]

    def stop(self) -> None:
        """Stop the MCP server."""
        self._adapter.__exit__(None, None, None)  # type: ignore[union-attr]

    @property
    def tools(self) -> ToolCollection[BaseTool]:
        """The CrewAI tools available from the MCP server.

        Raises:
            ValueError: If the MCP server is not started.

        Returns:
            The CrewAI tools available from the MCP server.

View on GitHub (pinned to 754d7323be)

Solutions

1. Read the chained cause in the traceback (`from e`) — the inner exception names the real problem (connection refused, command not found, timeout).
2. Verify the serverparams: for stdio, test the command manually (e.g. run `npx -y @modelcontextprotocol/server-filesystem .`) to confirm it launches.
3. Increase connect_timeout if the server is slow to start: MCPServerAdapt(params, connect_timeout=60).
4. Reinstall MCP extras: `uv add 'crewai-tools[mcp]'` to get compatible mcp/mcp-adapt versions.
5. For SSE servers, confirm the URL scheme/port and any required headers/auth in the serverparams dict.

Example fix

// before
server = MCPServerAdapt({"url": "http://localhost:9999/sse"})  # server not running

// after
server = MCPServerAdapt(
    {"url": "http://localhost:9999/sse"},
    connect_timeout=60,
)

from crewai_tools.adapters.mcp_adapter import MCPServerAdapt

def can_build(params) -> bool:
    try:
        with MCPServerAdapt(params, connect_timeout=60):
            return True
    except Exception:
        return False

try:
    server = MCPServerAdapt(params, connect_timeout=60)
except RuntimeError as e:
    cause = e.__cause__  # real failure: connection refused / bad command / timeout
    logger.error("MCP init failed: %s (cause: %s)", e, cause)
    raise

When it happens

Trigger: Constructing MCPServerAdapt(serverparams, ...) where serverparams is a malformed StdioServerParameters (e.g. wrong command path), an SSE dict with a wrong URL, an MCP server executable that fails/crashes on launch, or when MCPAdapt cannot connect within connect_timeout (default 30s). Also raised if self.start() (the __enter__ call on the adapter) throws.

Common situations: Passing a wrong command for a stdio MCP server (npx/node not found, bad package name), SSE server URL unreachable or requiring auth, mismatched mcp / mcp-adapt package versions after upgrading crewai-tools, or network/timeout issues when the MCP server is slow to boot.

Related errors

• Client is not initialized
• async is not supported by the CrewAI framework.
• Failed to install mcp package
• `mcp` package not found, please run `uv add crewai-tools[mcp
• MCP server not started, run `mcp_server.start()` first befor

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/27fc8b337e275797. Report an issue: GitHub.