Skip to main content
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:

​
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")

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

mcp.add_transform(Namespace("v1"))

# 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:
MethodPatternPurpose
list_tools(tools)Pure functionTransform the sequence of tools
get_tool(name, call_next)MiddlewareTransform lookup by name
list_resources(resources)Pure functionTransform the sequence of resources
get_resource(uri, call_next)MiddlewareTransform lookup by URI
list_resource_templates(templates)Pure functionTransform the sequence of templates
get_resource_template(uri, call_next)MiddlewareTransform template lookup by URI
list_prompts(prompts)Pure functionTransform the sequence of prompts
get_prompt(name, call_next)MiddlewareTransform 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