fix(harness): page MCP resources with the SDK and pass cursors through

- Listing every server's resources or templates uses the SDK's own
  pagination and its limits, so a server repeating a cursor cannot keep
  a listing running.
- A cursor goes back to the server exactly as it was given; only server
  names and URIs are trimmed.
- Tests remove the files they save, and read saved paths between the
  message's own delimiters.
- Docs: which servers a message waits for, exposure changes keep a
  server running, and where server logs go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sanchitrk

packages/harness/src/mcp/client.ts

@@ -63,6 +63,10 @@ export interface Connection {
 	readonly resources: (cursor?: string) => Effect.Effect<ListResourcesResult, Failed>;
 	/** One page of resource templates; empty when the server does not implement the method. */
 	readonly resourceTemplates: (cursor?: string) => Effect.Effect<ListResourceTemplatesResult, Failed>;
+	/** Every resource, following pagination with the SDK's limits. */
+	readonly allResources: () => Effect.Effect<ListResourcesResult["resources"], Failed>;
+	/** Every resource template, following pagination; empty when the server does not implement the method. */
+	readonly allResourceTemplates: () => Effect.Effect<ListResourceTemplatesResult["resourceTemplates"], Failed>;
 	readonly readResource: (uri: string) => Effect.Effect<ReadResourceResult, Failed>;
 	readonly callTool: (input: {
 		readonly name: string;
@@ -395,6 +399,21 @@ export const connect = Effect.fn("McpClient.connect")(function* (input: ConnectI
 		onprogress: onProgress ?? (() => {}),
 	});
 	const capabilities = client.getServerCapabilities();
+	// Servers that do not implement templates have none.
+	const templates = (run: (signal: AbortSignal) => Promise<ListResourceTemplatesResult>) =>
+		capabilities?.resources === undefined
+			? Effect.succeed<ListResourceTemplatesResult>({ resourceTemplates: [] })
+			: settle(
+					"resources/templates/list",
+					retrying("resources/templates/list", attempt(run)).pipe(
+						Effect.catchIf(
+							(failure) =>
+								failure.error instanceof ProtocolError &&
+								failure.error.code === ProtocolErrorCode.MethodNotFound,
+							() => Effect.succeed<ListResourceTemplatesResult>({ resourceTemplates: [] }),
+						),
+					),
+				);
 
 	const connection: Connection = {
 		serverInfo: client.getServerVersion(),
@@ -417,28 +436,22 @@ export const connect = Effect.fn("McpClient.connect")(function* (input: ConnectI
 						),
 					),
 		resourceTemplates: (cursor) =>
+			templates((signal) =>
+				client.request(
+					{ method: "resources/templates/list", params: cursor === undefined ? {} : { cursor } },
+					options(signal),
+				),
+			),
+		allResources: () =>
 			capabilities?.resources === undefined
-				? Effect.succeed({ resourceTemplates: [] })
-				: settle(
-						"resources/templates/list",
-						retrying(
-							"resources/templates/list",
-							attempt((signal) =>
-								client.request(
-									{ method: "resources/templates/list", params: cursor === undefined ? {} : { cursor } },
-									options(signal),
-								),
-							),
-						).pipe(
-							// Servers that do not implement templates have none.
-							Effect.catchIf(
-								(failure) =>
-									failure.error instanceof ProtocolError &&
-									failure.error.code === ProtocolErrorCode.MethodNotFound,
-								() => Effect.succeed({ resourceTemplates: [] }),
-							),
-						),
+				? Effect.succeed([])
+				: read("resources/list", (signal) => client.listResources(undefined, options(signal))).pipe(
+						Effect.map((result) => result.resources),
 					),
+		allResourceTemplates: () =>
+			templates((signal) => client.listResourceTemplates(undefined, options(signal))).pipe(
+				Effect.map((result) => result.resourceTemplates),
+			),
 		readResource: (uri) => read("resources/read", (signal) => client.readResource({ uri }, options(signal))),
 		callTool: (call) =>
 			request("tools/call", (signal) =>

packages/harness/src/mcp/mcp.ts

@@ -382,6 +382,8 @@ export const layer = (options: { readonly hostCwd: string; readonly home: string
 					name,
 					resources: (cursor) => reach((connection) => connection.resources(cursor)),
 					templates: (cursor) => reach((connection) => connection.resourceTemplates(cursor)),
+					allResources: () => reach((connection) => connection.allResources()),
+					allTemplates: () => reach((connection) => connection.allResourceTemplates()),
 					read: (uri) => reach((connection) => connection.readResource(uri)),
 				};
 			};

packages/harness/src/mcp/resources.ts

@@ -32,6 +32,9 @@ export interface Server {
 	readonly name: string;
 	readonly resources: (cursor?: string) => Effect.Effect<ListResourcesResult, string>;
 	readonly templates: (cursor?: string) => Effect.Effect<ListResourceTemplatesResult, string>;
+	/** Every page, with the SDK's own pagination limits. */
+	readonly allResources: () => Effect.Effect<ReadonlyArray<Resource>, string>;
+	readonly allTemplates: () => Effect.Effect<ReadonlyArray<ResourceTemplate>, string>;
 	readonly read: (uri: string) => Effect.Effect<ReadResourceResult, string>;
 }
 
@@ -70,14 +73,18 @@ const READ_PARAMETERS = {
 	additionalProperties: false,
 };
 
-/** A string argument, trimmed; absent when missing or blank. */
-const argument = (args: Record<string, unknown>, key: string): Effect.Effect<string | undefined, string> => {
+/** A string argument; absent when missing. */
+const raw = (args: Record<string, unknown>, key: string): Effect.Effect<string | undefined, string> => {
 	const value = args[key];
 	if (value === undefined || value === null) return Effect.undefined;
 	if (!Predicate.isString(value)) return Effect.fail(`${key} must be a string`);
-	return Effect.succeed(value.trim() || undefined);
+	return Effect.succeed(value);
 };
 
+/** A name the model typed: trimmed, and absent when blank. */
+const argument = (args: Record<string, unknown>, key: string) =>
+	raw(args, key).pipe(Effect.map((value) => value?.trim() || undefined));
+
 type Item = Resource | ResourceTemplate;
 type Page = { readonly items: ReadonlyArray<Item>; readonly nextCursor?: string | undefined };
 
@@ -106,10 +113,12 @@ export const make = (input: {
 	const list = (
 		key: "resources" | "resourceTemplates",
 		page: (server: Server, cursor?: string) => Effect.Effect<Page, string>,
+		all: (server: Server) => Effect.Effect<ReadonlyArray<Item>, string>,
 	) =>
 		Effect.fnUntraced(function* (args: Record<string, unknown>) {
 			const name = yield* argument(args, "server");
-			const cursor = yield* argument(args, "cursor");
+			// A cursor is the server's opaque token, handed back exactly as it was given.
+			const cursor = yield* raw(args, "cursor");
 			const visible = (item: Item) => !isMcpApp(item);
 			if (name !== undefined) {
 				const server = yield* find(name);
@@ -122,18 +131,7 @@ export const make = (input: {
 			}
 			if (cursor !== undefined) return yield* Effect.fail("cursor can only be used when a server is specified");
 			const servers = [...input.servers()].sort((a, b) => a.name.localeCompare(b.name));
-			const every = (server: Server) =>
-				Effect.gen(function* () {
-					const items: Item[] = [];
-					let next: string | undefined;
-					do {
-						const result = yield* page(server, next);
-						items.push(...result.items);
-						next = result.nextCursor;
-					} while (next !== undefined);
-					return items;
-				});
-			const results = yield* Effect.forEach(servers, (server) => Effect.result(every(server)), {
+			const results = yield* Effect.forEach(servers, (server) => Effect.result(all(server)), {
 				concurrency: "unbounded",
 			});
 			const items: Record<string, unknown>[] = [];
@@ -178,10 +176,13 @@ export const make = (input: {
 			server: "",
 			tool: LIST_RESOURCES_TOOL,
 			run: ({ args }) =>
-				list("resources", (server, cursor) =>
-					server
-						.resources(cursor)
-						.pipe(Effect.map((result) => ({ items: result.resources, nextCursor: result.nextCursor }))),
+				list(
+					"resources",
+					(server, cursor) =>
+						server
+							.resources(cursor)
+							.pipe(Effect.map((result) => ({ items: result.resources, nextCursor: result.nextCursor }))),
+					(server) => server.allResources(),
 				)(args),
 		}),
 		McpTool.define({
@@ -193,10 +194,15 @@ export const make = (input: {
 			server: "",
 			tool: LIST_TEMPLATES_TOOL,
 			run: ({ args }) =>
-				list("resourceTemplates", (server, cursor) =>
-					server
-						.templates(cursor)
-						.pipe(Effect.map((result) => ({ items: result.resourceTemplates, nextCursor: result.nextCursor }))),
+				list(
+					"resourceTemplates",
+					(server, cursor) =>
+						server
+							.templates(cursor)
+							.pipe(
+								Effect.map((result) => ({ items: result.resourceTemplates, nextCursor: result.nextCursor })),
+							),
+					(server) => server.allTemplates(),
 				)(args),
 		}),
 		McpTool.define({

packages/harness/test/__artifacts__/mcp.session.json

@@ -156,7 +156,7 @@
 			"status": "completed",
 			"isError": false,
 			"content": [
-				"{\"server\":\"e2e\",\"resources\":[{\"server\":\"e2e\",\"name\":\"notes\",\"uri\":\"fixture://notes.txt\",\"mimeType\":\"text/plain\"}],\"nextCursor\":\"page-2\"}"
+				"{\"server\":\"e2e\",\"resources\":[{\"server\":\"e2e\",\"name\":\"notes\",\"uri\":\"fixture://notes.txt\",\"mimeType\":\"text/plain\"}],\"nextCursor\":\" page-2 \"}"
 			]
 		},
 		"resources-next": {

packages/harness/test/fixtures/mcp/session.mjs

@@ -34,9 +34,9 @@ const resources = {
 			{ uri: "fixture://notes.txt", name: "notes", mimeType: "text/plain" },
 			{ uri: "ui://widget", name: "widget" },
 		],
-		nextCursor: "page-2",
+		nextCursor: " page-2 ",
 	},
-	"page-2": { resources: [{ uri: "fixture://data.bin", name: "data", mimeType: "application/octet-stream" }] },
+	" page-2 ": { resources: [{ uri: "fixture://data.bin", name: "data", mimeType: "application/octet-stream" }] },
 };
 const contents = {
 	"fixture://notes.txt": [{ uri: "fixture://notes.txt", mimeType: "text/plain", text: "the notes" }],

packages/harness/test/mcp.client.test.ts

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { LoggingMessageNotificationParams, OAuthClientProvider } from "@modelcontextprotocol/client";
 import { Deferred, Effect, Exit, Fiber, Option, Ref, Scope } from "effect";
-import { describe, expect, vi } from "vite-plus/test";
+import { describe, expect, onTestFinished, vi } from "vite-plus/test";
 import { McpClient } from "../src/mcp/client.ts";
 import { McpContent } from "../src/mcp/content.ts";
 import { McpLog } from "../src/mcp/log.ts";
@@ -72,7 +72,6 @@ const scenarios = [
 
 const normalise = (message: string) =>
 	message
-		.replace(/\S+codework-mcp-[0-9a-f]+(\.\w+)/g, "<output>$1")
 		.replaceAll(fixtures, "<fixtures>/")
 		.replaceAll(process.execPath, "<node>")
 		.replace(/127\.0\.0\.1:\d+/g, "127.0.0.1:<port>")
@@ -145,16 +144,17 @@ describe("mcp client", () => {
 				tools: tools.map((tool) => tool.name),
 				echo: converted.echo,
 				mixed: converted.mixed.map((block) =>
-					block.type === "text" ? { ...block, text: normalise(block.text) } : block,
+					block.type === "text"
+						? { ...block, text: block.text.replace(/saved to .+\]$/, "saved to <output>.bin]") }
+						: block,
 				),
 				structured: converted.structured,
 			};
 			expect(connection.instructions).toBe("Use the echo tool.");
 			expect(converted.echo).toEqual([{ type: "text", text: "hi" }]);
-			const saved = /saved to (\S+codework-mcp-[0-9a-f]+\.bin)\]$/.exec(
-				(converted.mixed[4] as { readonly text: string }).text,
-			)?.[1];
+			const saved = /saved to (.+)\]$/.exec((converted.mixed[4] as { readonly text: string }).text)?.[1];
 			expect(saved).toBeDefined();
+			onTestFinished(() => rmSync(saved!, { force: true }));
 			expect(yield* Effect.promise(() => readFile(saved!))).toEqual(Buffer.from([0, 1, 2]));
 			expect(converted.mixed).toEqual([
 				{ type: "text", text: "hello" },

packages/harness/test/mcp.session.test.ts

@@ -4,7 +4,7 @@ import { Effect } from "effect";
 import fs from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { expect, it } from "vite-plus/test";
+import { expect, it, onTestFinished } from "vite-plus/test";
 import { ContextCodec } from "../src/context/codec.ts";
 import { Harness } from "../src/effect/harness.ts";
 import { Session } from "../src/effect/session.ts";
@@ -111,7 +111,8 @@ it("mcp: config layers, plugin bucket, direct tools, a crash mid-exchange and th
 				pendingCall("mcp__e2e__big", {}, "big"),
 				pendingCall("list_mcp_resources", {}, "resources-all"),
 				pendingCall("list_mcp_resources", { server: "e2e" }, "resources-page"),
-				pendingCall("list_mcp_resources", { server: "e2e", cursor: "page-2" }, "resources-next"),
+				// The server's cursor goes back exactly as it was given, spaces and all.
+				pendingCall("list_mcp_resources", { server: "e2e", cursor: " page-2 " }, "resources-next"),
 				pendingCall("list_mcp_resource_templates", {}, "templates"),
 				pendingCall("read_mcp_resource", { server: "e2e", uri: "fixture://notes.txt" }, "read-text"),
 				pendingCall("read_mcp_resource", { server: "e2e", uri: "fixture://data.bin" }, "read-binary"),
@@ -186,10 +187,12 @@ it("mcp: config layers, plugin bucket, direct tools, a crash mid-exchange and th
 	expect(outcome("cwd")?.content).toEqual([await fs.realpath(join(work, "srv"))]);
 
 	// What the model is not shown in full is kept on the host, in files only the user can read.
-	const savedPath = (id: string) =>
-		/(\/\S+codework-mcp-[0-9a-f]+\.\w+)/.exec(outcome(id)?.content.join("\n") ?? "")?.[1];
-	const bigFile = savedPath("big");
-	const binaryFile = savedPath("read-binary");
+	// Paths are read between the message's own delimiters, so a temp directory with spaces still parses.
+	const bigFile = /\[Full output: (.+) \(read it with offset\/limit\)\]/.exec(outcome("big")?.content[0] ?? "")?.[1];
+	const binaryFile = /saved to (.+)\]$/.exec(outcome("read-binary")?.content[0] ?? "")?.[1];
+	onTestFinished(async () => {
+		for (const file of [bigFile, binaryFile]) if (file) await fs.rm(file, { force: true });
+	});
 	expect(await fs.readFile(bigFile!, "utf8")).toBe(`start ${"x".repeat(30 * 1024)} end`);
 	expect([...(await fs.readFile(binaryFile!))]).toEqual([0, 1, 2, 3]);
 	expect((await fs.stat(binaryFile!)).mode & 0o777).toBe(0o600);
@@ -201,7 +204,8 @@ it("mcp: config layers, plugin bucket, direct tools, a crash mid-exchange and th
 	const normalise = (value: unknown) =>
 		JSON.parse(
 			JSON.stringify(value)
-				.replace(/\/\S+?codework-mcp-[0-9a-f]+(\.\w+)/g, "<output>$1")
+				.replaceAll(bigFile!, "<output>.txt")
+				.replaceAll(binaryFile!, "<output>.bin")
 				.replaceAll(real, "<tmp>")
 				.replaceAll(dir.path, "<tmp>")
 				.replaceAll(process.execPath, "<node>")

sites/www/content/docs/customize/mcp.mdx

@@ -65,6 +65,7 @@ Servers with resources also add `list_mcp_resources`, `list_mcp_resource_templat
 
 ## Connections
 
-- Servers connect in the background. Your first message waits up to 10 seconds for servers whose tools the model sees.
+- Servers connect in the background. A message waits up to 10 seconds for servers it starts whose tools the model sees: all of them at first, then new or changed ones.
 - If a server stops, the next call starts it again.
-- Edits to `mcp.json` apply from your next message.
+- Edits to `mcp.json` apply from your next message. Changing only `exposure` or `toolExposure` keeps the server running.
+- Server log messages go to `~/.codework/mcp.log`.