huggingface/smolagents · error · ImportError

Please install 'mcp' extra to use ToolCollection.from_mcp: `

Error message

Please install 'mcp' extra to use ToolCollection.from_mcp: `pip install 'smolagents[mcp]'`.

What it means

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.

Source

Thrown at src/smolagents/tools.py:1040

        ```
        """
        # 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 ImportError:
            raise ImportError(
                """Please install 'mcp' extra to use ToolCollection.from_mcp: `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'."
                )
        if not trust_remote_code:
            raise ValueError(
                "Loading tools from MCP requires you to acknowledge you trust the MCP server, "
                "as it will execute code on your local machine: pass `trust_remote_code=True`."
            )
        with MCPAdapt(server_parameters, SmolAgentsAdapter(structured_output=structured_output)) as tools:
            yield cls(tools)

View on GitHub (pinned to 30bb116109)

Solutions

  1. Install the extra: `pip install 'smolagents[mcp]'`
  2. Add 'smolagents[mcp]' to your requirements.txt/pyproject dependency list so rebuilds keep it
  3. Verify with `python -c "import mcpadapt.core"` before running MCP-dependent code

Example fix

# before
ToolCollection.from_mcp({"url": "http://localhost:8000/mcp"}, trust_remote_code=True)
# after  (after: pip install 'smolagents[mcp]')
ToolCollection.from_mcp({"url": "http://localhost:8000/mcp", "transport": "streamable-http"}, trust_remote_code=True)
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("mcpadapt") is None:
    raise SystemExit("Run: pip install 'smolagents[mcp]'")
tools = ToolCollection.from_mcp(params, trust_remote_code=True)

Try / catch

try:
    with ToolCollection.from_mcp(params, trust_remote_code=True) as tools:
        ...
except ImportError as e:
    if "smolagents[mcp]" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", "smolagents[mcp]"])

Prevention

When it happens

Trigger: 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.

Common situations: 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.

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/fb62ace92a05ff39. Report an issue: GitHub.