Skip to main content
Roots allow your MCP server to discover which directories or files the client has made available.

​
Basic Usage

Use the list_roots() method on the context object: 
from mcp_use.server import Context, MCPServer

server = MCPServer(name="File Server")

@server.tool()
async def get_workspace_info(ctx: Context) -> str:
    """Get information about the client's available workspaces."""
    roots = await ctx.list_roots()

    if not roots:
        return "No roots available from client"

    lines = [f"Available workspaces ({len(roots)}):"]
    for root in roots:
        name = root.name or "(unnamed)"
        lines.append(f"  - {name}: {root.uri}")

    return "\n".join(lines)

​
Root Object Structure

Each Root object returned by list_roots() contains:
FieldTypeDescription
uriAnyUrlA file:// URI pointing to the root directory or file
namestr | NoneOptional human-readable name for the root

​
Use Cases

​
File Search Tool

@server.tool()
async def search_files(pattern: str, ctx: Context) -> str:
    """Search for files matching a pattern in client workspaces."""
    roots = await ctx.list_roots()

    if not roots:
        return "No workspaces available to search"

    results = []
    for root in roots:
        path = str(root.uri).replace("file://", "")
        # Search logic here...
        results.append(f"Searched in: {root.name or path}")

    return "\n".join(results)

​
Project Analyzer

@server.tool()
async def analyze_project(ctx: Context) -> dict:
    """Analyze the client's project structure."""
    roots = await ctx.list_roots()

    return {
        "total_roots": len(roots),
        "projects": [
            {"name": root.name, "path": str(root.uri)}
            for root in roots
        ]
    }