{"record":{"id":"5248b08f9f13a8f2","repo":"PrefectHQ/fastmcp","slug":"mcp-configs-that-use-fastmcp-specific-tool-transfo","errorCode":null,"errorMessage":"MCP configs that use FastMCP-specific tool transforms or tag filters","messagePattern":"MCP configs that use FastMCP-specific tool transforms or tag filters","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/mcp_config.py","lineNumber":134,"sourceCode":"            has_exclude = values.get(\"exclude_tags\") is not None\n            if not (has_tools or has_include or has_exclude):\n                raise ValueError(\n                    \"At least one of 'tools', 'include_tags', or 'exclude_tags' is required\"\n                )\n        return values\n\n    def _to_server_and_underlying_transport(\n        self,\n        server_name: str | None = None,\n        client_name: str | None = None,\n    ) -> tuple[Any, ClientTransport]:\n        \"\"\"Turn the transforming server into a FastMCP proxy and return its transport.\"\"\"\n        try:\n            from fastmcp import Client\n            from fastmcp.server import create_proxy\n            from fastmcp.server.transforms import ToolTransform\n        except ImportError as exc:\n            raise ImportError(\n                _install_hints.full_package(\n                    \"MCP configs that use FastMCP-specific tool transforms or tag filters\"\n                )\n            ) from exc\n\n        transport = cast(\"ClientTransport\", super().to_transport())  # ty: ignore[unresolved-attribute]\n        # The proxy that wraps this client forwards the initialize handshake and\n        # server-initiated features, which require the legacy era.\n        client = Client(transport=transport, name=client_name, mode=\"legacy\")\n        wrapped_mcp_server = create_proxy(client, name=server_name)\n\n        if self.include_tags is not None:\n            wrapped_mcp_server.enable(tags=self.include_tags, only=True)\n        if self.exclude_tags is not None:\n            wrapped_mcp_server.disable(tags=self.exclude_tags)\n        if self.tools:\n            wrapped_mcp_server.add_transform(\n                ToolTransform(_coerce_tool_transform_configs(self.tools))","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/mcp_config.py#L116-L152","documentation":"_to_server_and_underlying_transport builds a FastMCP proxy server, which needs the full fastmcp package (Client, create_proxy, ToolTransform). When those imports fail — typically because only the slim/core package is installed — it raises ImportError with an install hint naming the feature that requires the full package.","triggerScenarios":"Calling _to_server_and_underlying_transport (directly or via to_transport) on a transforming MCP config while fastmcp's client/server modules are not importable, e.g. running under 'fastmcp-slim' or a partial install.","commonSituations":"Projects that installed a slim distribution for server-only use but then load an MCP config that uses tool transforms or tag filters; CI environments with trimmed dependencies.","solutions":["Install the full package: pip/uv install fastmcp (not the slim variant)","Remove tools/include_tags/exclude_tags from the config so the transforming path is not used","Verify with 'python -c \"from fastmcp import Client\"' that the import works in the active environment"],"exampleFix":"// before\nuv pip install fastmcp-slim\n// after\nuv pip install fastmcp","handlingStrategy":"try-catch","validationCode":"try:\n    from fastmcp import Client  # noqa\n    FULL_FASTMCP = True\nexcept ImportError:\n    FULL_FASTMCP = False","typeGuard":null,"tryCatchPattern":"try:\n    transport = cfg.to_transport()\nexcept ImportError as e:\n    raise RuntimeError(\"Install the full fastmcp package: pip install fastmcp\") from e","preventionTips":["Install the full fastmcp distribution when using tool transforms/tag filters","Add an import check early in app startup","Document the fastmcp (non-slim) requirement for transforming configs"],"tags":["import","installation","dependency","mcp"],"backgroundTag":"missing-optional-dependency","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}