> ## Documentation Index

> Fetch the complete documentation index at: /llms.txt

> Use this file to discover all available pages before exploring further.

Skip to main content
Working with Tools

# Transforms Overview

Modify components as they flow through your server

New in version `3.0.0` Transforms modify components as they flow from providers to clients. When a client asks “what tools do you have?”, the request passes through each transform in the chain. Each transform can modify the components before passing them along.

##
​
Mental Model

Think of transforms as filters in a pipeline. Components flow from providers through transforms to reach clients:

    Provider → [Transform A] → [Transform B] → Client

When listing components, transforms receive sequences and return transformed sequences—a pure function pattern. When getting a specific component by name, transforms use a middleware pattern with `call_next`, working in reverse: mapping the client’s requested name back to the original, then transforming the result.

##
​
Built-in Transforms

FastMCP provides several transforms for common use cases:

- Namespace - Prefix component names to prevent conflicts when composing servers
- Tool Transformation - Rename tools, modify descriptions, reshape arguments
- Enabled - Control which components are visible at runtime
- Tool Search - Replace large tool catalogs with on-demand search
- Resources as Tools - Expose resources to tool-only clients
- Prompts as Tools - Expose prompts to tool-only clients
- Code Mode (Experimental) - Replace many tools with programmable `search` + `execute`

##
​
Server vs Provider Transforms

Transforms can be added at two levels, each serving different purposes.

###
​
Provider-Level Transforms

Provider transforms apply to components from a specific provider. They run first, modifying components before they reach the server level.

    from fastmcp import FastMCP
    from fastmcp.server.providers import FastMCPProvider
    from fastmcp.server.transforms import Namespace, ToolTransform
    from fastmcp.tools.tool_transform import ToolTransformConfig

    sub_server = FastMCP("Sub")

    @sub_server.tool
    def process(data: str) -> str:
        return f"Processed: {data}"

    # Create provider and add transforms
    provider = FastMCPProvider(sub_server)
    provider.add_transform(Namespace("api"))
    provider.add_transform(ToolTransform({
        "api_process": ToolTransformConfig(description="Process data through the API"),
    }))

    main = FastMCP("Main", providers=[provider])
    # Tool is now: api_process with updated description

When using `mount()`, the returned provider reference lets you add transforms directly.

    main = FastMCP("Main")
    mount = main.mount(sub_server, namespace="api")
    mount.add_transform(ToolTransform({...}))

###
​
Server-Level Transforms

Server transforms apply to all components from all providers. They run after provider transforms, seeing the already-transformed names.

    from fastmcp import FastMCP
    from fastmcp.server.transforms import Namespace

    mcp = FastMCP("Server", transforms=[Namespace("v1")])

    @mcp.tool
    def greet(name: str) -> str:
        return f"Hello, {name}!"

    # All tools become v1_toolname

Server-level transforms are useful for API versioning or applying consistent naming across your entire server.

###
​
Transform Order

Transforms stack in the order they’re added. The first transform added is innermost (closest to the provider), and subsequent transforms wrap it.

    from fastmcp.server.providers import FastMCPProvider
    from fastmcp.server.transforms import Namespace, ToolTransform
    from fastmcp.tools.tool_transform import ToolTransformConfig

    provider = FastMCPProvider(server)
    provider.add_transform(Namespace("api"))           # Applied first
    provider.add_transform(ToolTransform({             # Sees namespaced names
        "api_verbose_name": ToolTransformConfig(name="short"),
    }))

    # Flow: "verbose_name" -> "api_verbose_name" -> "short"

When a client requests “short”, the transforms reverse the mapping: ToolTransform maps “short” to “api_verbose_name”, then Namespace strips the prefix to find “verbose_name” in the provider.

##
​
Custom Transforms

Create custom transforms by subclassing `Transform` and overriding the methods you need.

    from collections.abc import Sequence
    from fastmcp.server.transforms import Transform, GetToolNext
    from fastmcp.tools.tool import Tool

    class TagFilter(Transform):
        """Filter tools to only those with specific tags."""

        def __init__(self, required_tags: set[str]):
            self.required_tags = required_tags

        async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
            return [t for t in tools if t.tags & self.required_tags]

        async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:
            tool = await call_next(name)
            if tool and tool.tags & self.required_tags:
                return tool
            return None

The `Transform` base class provides default implementations that pass through unchanged. Override only the methods relevant to your transform. Each component type has two methods with different patterns:

Method | Pattern | Purpose
--- | --- | ---
`list_tools(tools)` | Pure function | Transform the sequence of tools
`get_tool(name, call_next)` | Middleware | Transform lookup by name
`list_resources(resources)` | Pure function | Transform the sequence of resources
`get_resource(uri, call_next)` | Middleware | Transform lookup by URI
`list_resource_templates(templates)` | Pure function | Transform the sequence of templates
`get_resource_template(uri, call_next)` | Middleware | Transform template lookup by URI
`list_prompts(prompts)` | Pure function | Transform the sequence of prompts
`get_prompt(name, call_next)` | Middleware | Transform lookup by name

List methods receive sequences directly and return transformed sequences. Get methods use `call_next` for routing flexibility—when a client requests “new_name”, your transform maps it back to “original_name” before calling `call_next()`.

    class PrefixTransform(Transform):
        def __init__(self, prefix: str):
            self.prefix = prefix

        async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
            return [t.model_copy(update={"name": f"{self.prefix}_{t.name}"}) for t in tools]

        async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:
            # Reverse the prefix to find the original
            if not name.startswith(f"{self.prefix}_"):
                return None
            original = name[len(self.prefix) + 1:]
            tool = await call_next(original)
            if tool:
                return tool.model_copy(update={"name": name})
            return None

MCP Context
Previous
Tool Transformation
Next
Ctrl+I
Assistant
Responses are generated using AI and may contain mistakes.
\n\n
\n
\n \n
\n
","contacts":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","dashboard":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","data-table":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","hitchhikers":" \n
\n\n Prefab Showcase\n \n \n \n \n\n
\n
\n \n
\n
","pie-chart":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","reactive":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","team-directory-reactive":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
","team-directory":" \n
\n\n Prefab\n \n \n \n \n\n
\n
\n \n
\n
"};