{"record":{"id":"0c8bb267698447af","repo":"huggingface/smolagents","slug":"please-install-mcp-extra-to-use-mcpclient-pip","errorCode":null,"errorMessage":"Please install 'mcp' extra to use MCPClient: `pip install 'smolagents[mcp]'`","messagePattern":"Please install 'mcp' extra to use MCPClient: `pip install 'smolagents\\[mcp\\]'`","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"src/smolagents/mcp_client.py","lineNumber":107,"sourceCode":"        structured_output: bool | None = None,\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 ModuleNotFoundError:\n            raise ModuleNotFoundError(\"Please install 'mcp' extra to use MCPClient: `pip install 'smolagents[mcp]'`\")\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        adapter_kwargs = adapter_kwargs or {}\n        self._adapter = MCPAdapt(\n            server_parameters, SmolAgentsAdapter(structured_output=structured_output), **adapter_kwargs\n        )\n        self._tools: list[Tool] | None = None\n        self.connect()\n\n    def connect(self):\n        \"\"\"Connect to the MCP server and initialize the tools.\"\"\"","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/mcp_client.py#L89-L125","documentation":"Importing MCPClient only succeeds if the optional mcp extra is installed; its __init__ tries to import mcpadapt.core and mcpadapt.smolagents_adapter, and on ModuleNotFoundError re-raises with a pip install hint. MCPClient is a thin wrapper around MCPAdapt for connecting agents to Model Context Protocol servers.","triggerScenarios":"Constructing MCPClient (or using an agent framework feature that instantiates it) without having run `pip install 'smolagents[mcp]'`, so the mcpadapt dependency is missing.","commonSituations":"Copying MCP example code into an environment where smolagents was installed without extras; CI environments with minimal dependency sets; upgrading smolagents without reinstalling extras.","solutions":["Run `pip install 'smolagents[mcp]'` (or `pip install smolagents[mcp]` / add the extra in pyproject)","If you don't need MCP, remove the MCPClient import and code path","Pin extras in requirements: `smolagents[mcp]` so installs are reproducible"],"exampleFix":"# before\nfrom smolagents.mcp_client import MCPClient  # ModuleNotFoundError\n\n# after (shell)\n# pip install 'smolagents[mcp]'\nfrom smolagents.mcp_client import MCPClient","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\nif find_spec('mcpadapt') is None:\n    raise SystemExit(\"Install with: pip install 'smolagents[mcp]'\")","typeGuard":"from importlib.util import find_spec\n\ndef mcp_extra_available() -> bool:\n    return find_spec('mcpadapt') is not None and find_spec('mcpadapt.smolagents_adapter') is not None","tryCatchPattern":"try:\n    from smolagents.mcp_client import MCPClient\nexcept ModuleNotFoundError as e:\n    if \"smolagents[mcp]\" in str(e):\n        print('MCP support missing; skipping MCP tools')\n        MCPClient = None","preventionTips":["Install extras declaratively: pip install 'smolagents[mcp]'","Guard MCP imports behind availability checks in optional code paths","Document extras in your project's dependency spec"],"tags":["smolagents","mcp","optional-dependency","module-not-found"],"backgroundTag":"missing-optional-dependency","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}