{"record":{"id":"fb62ace92a05ff39","repo":"huggingface/smolagents","slug":"please-install-mcp-extra-to-use-toolcollection-f","errorCode":null,"errorMessage":"Please install 'mcp' extra to use ToolCollection.from_mcp: `pip install 'smolagents[mcp]'`.","messagePattern":"Please install 'mcp' extra to use ToolCollection\\.from_mcp: `pip install 'smolagents\\[mcp\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/smolagents/tools.py","lineNumber":1040,"sourceCode":"        ```\n        \"\"\"\n        # Handle future warning for structured_output default value change\n        if structured_output is None:\n            warnings.warn(\n                \"Parameter 'structured_output' was not specified. \"\n                \"Currently it defaults to False, but in version 1.25, the default will change to True. \"\n                \"To suppress this warning, explicitly set structured_output=True (new behavior) or structured_output=False (legacy behavior). \"\n                \"See documentation at https://huggingface.co/docs/smolagents/tutorials/tools#structured-output-and-output-schema-support for more details.\",\n                FutureWarning,\n                stacklevel=2,\n            )\n            structured_output = False\n\n        try:\n            from mcpadapt.core import MCPAdapt\n            from mcpadapt.smolagents_adapter import SmolAgentsAdapter\n        except ImportError:\n            raise ImportError(\n                \"\"\"Please install 'mcp' extra to use ToolCollection.from_mcp: `pip install 'smolagents[mcp]'`.\"\"\"\n            )\n        if isinstance(server_parameters, dict):\n            transport = server_parameters.get(\"transport\")\n            if transport is None:\n                transport = \"streamable-http\"\n                server_parameters[\"transport\"] = transport\n            if transport not in {\"sse\", \"streamable-http\"}:\n                raise ValueError(\n                    f\"Unsupported transport: {transport}. Supported transports are 'streamable-http' and 'sse'.\"\n                )\n        if not trust_remote_code:\n            raise ValueError(\n                \"Loading tools from MCP requires you to acknowledge you trust the MCP server, \"\n                \"as it will execute code on your local machine: pass `trust_remote_code=True`.\"\n            )\n        with MCPAdapt(server_parameters, SmolAgentsAdapter(structured_output=structured_output)) as tools:\n            yield cls(tools)","sourceCodeStart":1022,"sourceCodeEnd":1058,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/tools.py#L1022-L1058","documentation":"ToolCollection.from_mcp requires the MCP integration packages (mcpadapt and its smolagents adapter), which are shipped only in the `mcp` extra. The classmethod catches the ImportError of mcpadapt.core/mcpadapt.smolagents_adapter and re-raises with installation instructions.","triggerScenarios":"Calling `ToolCollection.from_mcp(server_parameters, trust_remote_code=True)` without `pip install 'smolagents[mcp]'` having been run, so `from mcpadapt.core import MCPAdapt` fails.","commonSituations":"Using MCP server tooling in a base smolagents install; upgrading smolagents without reinstalling extras; fresh environments provisioned from a requirements.txt that omits the mcp extra.","solutions":["Install the extra: `pip install 'smolagents[mcp]'`","Add 'smolagents[mcp]' to your requirements.txt/pyproject dependency list so rebuilds keep it","Verify with `python -c \"import mcpadapt.core\"` before running MCP-dependent code"],"exampleFix":"# before\nToolCollection.from_mcp({\"url\": \"http://localhost:8000/mcp\"}, trust_remote_code=True)\n# after  (after: pip install 'smolagents[mcp]')\nToolCollection.from_mcp({\"url\": \"http://localhost:8000/mcp\", \"transport\": \"streamable-http\"}, trust_remote_code=True)","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec(\"mcpadapt\") is None:\n    raise SystemExit(\"Run: pip install 'smolagents[mcp]'\")\ntools = ToolCollection.from_mcp(params, trust_remote_code=True)","typeGuard":null,"tryCatchPattern":"try:\n    with ToolCollection.from_mcp(params, trust_remote_code=True) as tools:\n        ...\nexcept ImportError as e:\n    if \"smolagents[mcp]\" in str(e):\n        subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"smolagents[mcp]\"])","preventionTips":["Pin 'smolagents[mcp]' in dependency files","Verify mcpadapt importability in a startup health check"],"tags":["mcp","optional-dependency","importerror","toolcollection"],"backgroundTag":"missing-optional-dependency","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}