huggingface/smolagents · error · ModuleNotFoundError

Please install 'mcp' extra to use MCPClient: `pip install 's

Error message

Please install 'mcp' extra to use MCPClient: `pip install 'smolagents[mcp]'`

What it means

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.

Source

Thrown at src/smolagents/mcp_client.py:107

        structured_output: bool | None = None,
    ):
        # Handle future warning for structured_output default value change
        if structured_output is None:
            warnings.warn(
                "Parameter 'structured_output' was not specified. "
                "Currently it defaults to False, but in version 1.25, the default will change to True. "
                "To suppress this warning, explicitly set structured_output=True (new behavior) or structured_output=False (legacy behavior). "
                "See documentation at https://huggingface.co/docs/smolagents/tutorials/tools#structured-output-and-output-schema-support for more details.",
                FutureWarning,
                stacklevel=2,
            )
            structured_output = False

        try:
            from mcpadapt.core import MCPAdapt
            from mcpadapt.smolagents_adapter import SmolAgentsAdapter
        except ModuleNotFoundError:
            raise ModuleNotFoundError("Please install 'mcp' extra to use MCPClient: `pip install 'smolagents[mcp]'`")
        if isinstance(server_parameters, dict):
            transport = server_parameters.get("transport")
            if transport is None:
                transport = "streamable-http"
                server_parameters["transport"] = transport
            if transport not in {"sse", "streamable-http"}:
                raise ValueError(
                    f"Unsupported transport: {transport}. Supported transports are 'streamable-http' and 'sse'."
                )
        adapter_kwargs = adapter_kwargs or {}
        self._adapter = MCPAdapt(
            server_parameters, SmolAgentsAdapter(structured_output=structured_output), **adapter_kwargs
        )
        self._tools: list[Tool] | None = None
        self.connect()

    def connect(self):
        """Connect to the MCP server and initialize the tools."""

View on GitHub (pinned to 30bb116109)

Solutions

  1. Run `pip install 'smolagents[mcp]'` (or `pip install smolagents[mcp]` / add the extra in pyproject)
  2. If you don't need MCP, remove the MCPClient import and code path
  3. Pin extras in requirements: `smolagents[mcp]` so installs are reproducible

Example fix

# before
from smolagents.mcp_client import MCPClient  # ModuleNotFoundError

# after (shell)
# pip install 'smolagents[mcp]'
from smolagents.mcp_client import MCPClient
Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec
if find_spec('mcpadapt') is None:
    raise SystemExit("Install with: pip install 'smolagents[mcp]'")

Type guard

from importlib.util import find_spec

def mcp_extra_available() -> bool:
    return find_spec('mcpadapt') is not None and find_spec('mcpadapt.smolagents_adapter') is not None

Try / catch

try:
    from smolagents.mcp_client import MCPClient
except ModuleNotFoundError as e:
    if "smolagents[mcp]" in str(e):
        print('MCP support missing; skipping MCP tools')
        MCPClient = None

Prevention

When it happens

Trigger: Constructing MCPClient (or using an agent framework feature that instantiates it) without having run `pip install 'smolagents[mcp]'`, so the mcpadapt dependency is missing.

Common situations: Copying MCP example code into an environment where smolagents was installed without extras; CI environments with minimal dependency sets; upgrading smolagents without reinstalling extras.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/0c8bb267698447af. Report an issue: GitHub.