{"record":{"id":"27fc8b337e275797","repo":"crewAIInc/crewAI","slug":"failed-to-initialize-mcp-adapter-e","errorCode":null,"errorMessage":"Failed to initialize MCP Adapter: {e}","messagePattern":"Failed to initialize MCP Adapter: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/adapters/mcp_adapter.py","lineNumber":190,"sourceCode":"            else:\n                raise ImportError(\n                    \"`mcp` package not found, please run `uv add crewai-tools[mcp]`\"\n                )\n\n        try:\n            self._serverparams = serverparams\n            self._adapter = MCPAdapt(\n                self._serverparams, CrewAIToolAdapter(), connect_timeout\n            )\n            self.start()\n\n        except Exception as e:\n            if self._adapter is not None:\n                try:\n                    self.stop()\n                except Exception as stop_e:\n                    logger.error(f\"Error during stop cleanup: {stop_e}\")\n            raise RuntimeError(f\"Failed to initialize MCP Adapter: {e}\") from e\n\n    def start(self) -> None:\n        \"\"\"Start the MCP server and initialize the tools.\"\"\"\n        self._tools = self._adapter.__enter__()  # type: ignore[union-attr]\n\n    def stop(self) -> None:\n        \"\"\"Stop the MCP server.\"\"\"\n        self._adapter.__exit__(None, None, None)  # type: ignore[union-attr]\n\n    @property\n    def tools(self) -> ToolCollection[BaseTool]:\n        \"\"\"The CrewAI tools available from the MCP server.\n\n        Raises:\n            ValueError: If the MCP server is not started.\n\n        Returns:\n            The CrewAI tools available from the MCP server.","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/adapters/mcp_adapter.py#L172-L208","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the chained cause in the traceback (`from e`) — the inner exception names the real problem (connection refused, command not found, timeout).","Verify the serverparams: for stdio, test the command manually (e.g. run `npx -y @modelcontextprotocol/server-filesystem .`) to confirm it launches.","Increase connect_timeout if the server is slow to start: MCPServerAdapt(params, connect_timeout=60).","Reinstall MCP extras: `uv add 'crewai-tools[mcp]'` to get compatible mcp/mcp-adapt versions.","For SSE servers, confirm the URL scheme/port and any required headers/auth in the serverparams dict."],"exampleFix":"// before\nserver = MCPServerAdapt({\"url\": \"http://localhost:9999/sse\"})  # server not running\n\n// after\nserver = MCPServerAdapt(\n    {\"url\": \"http://localhost:9999/sse\"},\n    connect_timeout=60,\n)","handlingStrategy":"try-catch","validationCode":"from crewai_tools.adapters.mcp_adapter import MCPServerAdapt\n\ndef can_build(params) -> bool:\n    try:\n        with MCPServerAdapt(params, connect_timeout=60):\n            return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    server = MCPServerAdapt(params, connect_timeout=60)\nexcept RuntimeError as e:\n    cause = e.__cause__  # real failure: connection refused / bad command / timeout\n    logger.error(\"MCP init failed: %s (cause: %s)\", e, cause)\n    raise","preventionTips":["Smoke-test stdio server commands manually before wiring them into serverparams.","Use the context-manager form (`with MCPServerAdapt(...)`) so cleanup is automatic.","Set connect_timeout generously for slow-booting MCP servers (npx-based ones especially).","Pin compatible mcp / crewai-tools[mcp] versions in your lockfile."],"tags":["mcp","initialization","connection","crewai-tools"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}