> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roots

> Expose file system roots to MCP servers

<Info>
  Roots allow clients to expose directories or files that MCP servers can access or operate on.
</Info>

## Overview

Roots represent directories or files that the client wants to make available to the server. This is useful for file-based operations where the server needs to know which paths are accessible. The server can request the list of roots at any time using `ctx.list_roots()`.

## Configuration

To expose roots to MCP servers, provide a `roots` list when initializing the MCPClient:

<CodeGroup>
  ```python Python theme={null}
  from mcp.types import Root
  from mcp_use.client import MCPClient

  # Define roots to expose to servers
  roots = [
      Root(uri="file:///home/user/projects", name="Projects"),
      Root(uri="file:///home/user/documents", name="Documents"),
  ]

  # Initialize client with roots
  client = MCPClient(
      config="config.json",
      roots=roots
  )
  ```
</CodeGroup>

## Dynamic Roots Updates

You can update the roots dynamically after connecting to a server. The client will automatically notify the server when roots change:

```python theme={null}
from mcp.types import Root
from mcp_use.client import MCPClient

client = MCPClient(config="config.json")
await client.create_all_sessions()

session = client.get_session("my-server")

# Update roots dynamically
new_roots = [
    Root(uri="file:///home/user/new-project", name="New Project"),
]
await session.connector.set_roots(new_roots)

# Get current roots
current_roots = session.connector.get_roots()
```

## Custom Roots Callback

For advanced use cases, you can provide a custom callback that dynamically determines which roots to expose:

```python theme={null}
from mcp.types import ListRootsResult, Root
from mcp_use.client import MCPClient

async def custom_roots_callback(context):
    """Dynamically determine roots based on context."""
    # You could check user permissions, load from config, etc.
    return ListRootsResult(roots=[
        Root(uri="file:///dynamic/path", name="Dynamic Root"),
    ])

client = MCPClient(
    config="config.json",
    list_roots_callback=custom_roots_callback
)
```

<Note>
  When a custom `list_roots_callback` is provided, it takes precedence over the static `roots` list.
</Note>

## Root Structure

Each `Root` object has the following fields:

| Field  | Type     | Required | Description                                          |
| ------ | -------- | -------- | ---------------------------------------------------- |
| `uri`  | `AnyUrl` | Yes      | A file:// URI pointing to the root directory or file |
| `name` | `str`    | No       | A human-readable name for the root                   |

## Example: File Manager Server

Here's a complete example showing a client exposing roots to a file management server:

```python theme={null}
import asyncio
from mcp.types import Root
from mcp_use.client import MCPClient

async def main():
    # Expose workspace directories to the server
    roots = [
        Root(uri="file:///home/user/workspace", name="Workspace"),
        Root(uri="file:///home/user/config", name="Config Files"),
    ]

    config = {
        "mcpServers": {
            "file-manager": {"url": "http://localhost:8000/mcp"}
        }
    }

    client = MCPClient(config, roots=roots)

    try:
        await client.create_all_sessions()
        session = client.get_session("file-manager")

        # The server can now query available roots
        # and operate on files within them
        result = await session.call_tool("list_files", {})
        print(result.content[0].text)

    finally:
        await client.close_all_sessions()

if __name__ == "__main__":
    asyncio.run(main())
```

## Next Steps

* See [Server Roots](/python/server/roots) for how servers can request and use roots
* Learn about [Sampling](/python/client/sampling) for enabling LLM capabilities
* Explore [Elicitation](/python/client/elicitation) for user input requests