Support `roots/list` request from server to client

[bmingles]

I have an MCP server build using the SDK. I need it to determine the workspace context of the client that is attempting to execute its tools. As I understand it, a roots/list request from the MCP server to the client is the mechanism defined in the MCP spec to do this. There seem to possibly be some APIs in the SDK for this, but they don't seem to be documented at all.

Things I've tried:

1. Use the extra.sendRequest param while in a tool request handler

const result = await extra.sendRequest(
  { method: 'roots/list' } as const,
  ListRootsResultSchema
);

2. Use the server.listRoots method (also in the request handler)

const result = await mcpServer.server.listRoots()

I've tried each with stateful and stateless versions of StreamableHTTPServerTransport construction. All attempts hang until eventually timing out.

If this is not yet supported, my request is:

Implement support for `roots/list` requests from server to client

If it is supported, and I'm just using incorrectly, my request is:

Document `roots/list` requests from server to client

[felixweinberger]

I tested with a minimal example and couldn't reproduce any problems:

For clients to support roots/list:

const client = new Client(
  { name: "my-client", version: "1.0.0" },
  { capabilities: { roots: { listChanged: true } } }
);

client.setRequestHandler(ListRootsRequestSchema, async () => {
  return { roots: [{ uri: "file:///path/to/project", name: "My Project" }] };
});

For servers to request roots:

const result = await server.listRoots();

Maybe the MCP client you're using doesn't have a registered a roots handler? Marking as good first issue - we need to add this to our documentation/examples.

Alternatively, if you could provide a minimal example that demonstrates the exact issue you're facing that would be ideal?

[bmingles]

@felixweinberger The client in my case is VS Code Copilot. I am running the MCP server from a VS Code extension. The VS Code docs indicate that the client should be registering as supporting roots capabilities.

I don't see listRoots on McpServer type from @modelcontextprotocol/sdk/server/mcp.js. Is there a different server type I should be using? disregard comment about the type. In my case it's mcpServer.server.listRoots, but it still just hangs.

[karashiiro]

This does appear to be broken, I was going to use this for propagating the working directory to an MCP server but I'm running into the same issue, even when the client and server are both from the SDK. When I run this test client and server together, it prints Client capabilities: { roots: {} } and then hangs on the listRoots call. I also don't see any tests in the repo that might validate that this ever worked.

Server (serveHttp is just a wrapper around the bulky transport scaffolding)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { serveHttp } from "@karashiiro/mcp/http";

function createServer() {
  const server = new McpServer({
    name: "mcp-capabilities",
    version: "1.0.0",
  });

  server.server.oninitialized = async () => {
    const clientCaps = server.server.getClientCapabilities();
    console.log("Client capabilities:", clientCaps);

    const roots = await server.server.listRoots();
    console.log("Available roots:", roots);
  };

  return server;
}

await serveHttp(createServer, {
  port: 8080,
  sessions: {},
  endpoint: "/mcp",
});

Client

import {
    Client,
} from '@modelcontextprotocol/sdk/client';
import {
    ListRootsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import {
    StreamableHTTPClientTransport
} from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client(
    {
        name: 'example-client',
        version: '1.0.0'
    },
    {
        capabilities: {
            roots: {},
        },
    },
);

client.setRequestHandler(ListRootsRequestSchema, () => {
    console.log("Received listRoots request from server");
    return {
        roots: [
            {
                uri: 'x://example.com/root1',
                name: 'root1',
            },
            {
                uri: 'x://example.com/root2',
                name: 'root2',
            },
        ],
    };
});

const transport = new StreamableHTTPClientTransport(new URL("http://localhost:8080/mcp"), {});
await client.connect(transport);

[karashiiro]

fwiw this also doesn't work with Claude Code (what I was originally testing with)