Client Roots

New in version 2.0.0 Use this when you need to tell servers what local resources the client has access to. A root is a path your client is willing to expose — a project directory, a workspace, a document store. Servers read them to scope their work, so a tool that searches files searches where you pointed it, and a server that gets no roots has to ask the user for paths instead. Roots describe where the client can reach; the server takes them as its working boundary. Register them once with roots=, and the client answers however the server asks. A handshake-era server pushes a roots/list request down the open session and reads the reply mid-call; a modern (2026-07-28) server has no such channel, so it returns a roots request and fastmcp.Client fulfils it from the same registration and re-issues the call with the answer attached. The default mode="auto" negotiates whichever era the server speaks, so the examples below work on either — see protocol negotiation for how that choice is made, and the guard pattern for how a server issues the modern form.

Static Roots

When the paths are known up front, pass them as a list. The client holds them for the life of the connection and hands back the same set every time a server asks.

from fastmcp import Client

client = Client(
    "my_mcp_server.py",
    roots=["file:///path/to/root1", "file:///path/to/root2"]
)

Dynamic Roots

Pass a callback instead when the roots depend on something the client learns at runtime, such as the workspace the user has open. It runs at the moment a server asks, on either route, and receives the request context so you can see which request it is answering:

from fastmcp import Client
from fastmcp.client.roots import RequestContext

async def roots_callback(context: RequestContext) -> list[str]:
    print(f"Server requested roots (Request ID: {context.request_id})")
    return ["file:///path/to/root1", "file:///path/to/root2"]

client = Client(
    "my_mcp_server.py",
    roots=roots_callback
)

Get Started

Servers

Apps

Clients

Integrations

More

Static Roots

Dynamic Roots

​Static Roots

​Dynamic Roots

Static Roots

Dynamic Roots