---
schema: rendered-html/v1
title: "Transforms Overview - FastMCP"
source_url: https://gofastmcp.com/servers/transforms/transforms
generated_at: 2026-06-11T19:36:07.367542+00:00
---




[FastMCP home page![light logo](images/gofastmcp__com__servers__transforms__transforms__wordmark.avif)![dark logo](images/gofastmcp__com__servers__transforms__transforms__wordmark-white.avif)](gofastmcp__com.md)


- [PrefectHQ/fastmcp](https://github.com/PrefectHQ/fastmcp "PrefectHQ/fastmcp")
- [PrefectHQ/fastmcp](https://github.com/PrefectHQ/fastmcp "PrefectHQ/fastmcp")



Working with Tools

Transforms Overview









  - [Overview](/servers/transforms/transforms)
  - [Tool Transformation](gofastmcp__com__servers__transforms__tool-transformation.md)
  - [Code Mode

    NEW](gofastmcp__com__servers__transforms__code-mode.md)
  - [Tool Search

    NEW](gofastmcp__com__servers__transforms__tool-search.md)
  - [Namespace](gofastmcp__com__servers__transforms__namespace.md)
  - [Visibility

    NEW](gofastmcp__com__servers__visibility.md)
  - [Resources as Tools

    NEW](gofastmcp__com__servers__transforms__resources-as-tools.md)
  - [Prompts as Tools

    NEW](gofastmcp__com__servers__transforms__prompts-as-tools.md)
  - [Tool Fingerprinting](gofastmcp__com__servers__tool-fingerprinting.md)














- [Mental Model](#mental-model)
- [Built-in Transforms](#built-in-transforms)
- [Server vs Provider Transforms](#server-vs-provider-transforms)
  - [Provider-Level Transforms](#provider-level-transforms)
  - [Server-Level Transforms](#server-level-transforms)
  - [Transform Order](#transform-order)
- [Custom Transforms](#custom-transforms)

Working with Tools

# Transforms Overview


Modify components as they flow through your server


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) 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) Built-in Transforms

FastMCP provides several transforms for common use cases:

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

## [​](#server-vs-provider-transforms) Server vs Provider Transforms

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

### [​](#provider-level-transforms) 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.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-Level Transforms

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

from fastmcp.server.transforms import Namespace

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

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) 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) 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](gofastmcp__com__servers__context.md)[Tool Transformation

Next](gofastmcp__com__servers__transforms__tool-transformation.md)






