From 8fcec138d068c8d582f784e4c4a5cdee3825bbb0 Mon Sep 17 00:00:00 2001 From: Peder Date: Wed, 14 Jan 2026 20:58:17 +0100 Subject: [PATCH 1/3] feat(client): return empty lists when server lacks capability Per the MCP spec, "Both parties SHOULD respect capability negotiation." Previously, calling listPrompts/listResources/listTools on a server that didn't advertise those capabilities would still send the request, causing servers to log warnings and creating unnecessary traffic. Now the Client respects capability negotiation by default: - listPrompts() returns { prompts: [] } if server lacks prompts capability - listResources() returns { resources: [] } if server lacks resources capability - listResourceTemplates() returns { resourceTemplates: [] } if server lacks resources capability - listTools() returns { tools: [] } if server lacks tools capability Each logs a debug message when this occurs for visibility. The existing enforceStrictCapabilities option is preserved - when set to true, these methods will still throw errors as before. Co-Authored-By: Claude Opus 4.5 --- packages/client/src/client/client.ts | 24 +++++++ test/integration/test/client/client.test.ts | 73 +++++++++++++++++++++ 2 files changed, 97 insertions(+) diff --git a/packages/client/src/client/client.ts b/packages/client/src/client/client.ts index 8d96ba0bc..d499069c3 100644 --- a/packages/client/src/client/client.ts +++ b/packages/client/src/client/client.ts @@ -252,6 +252,7 @@ export class Client< private _experimental?: { tasks: ExperimentalClientTasks }; private _listChangedDebounceTimers: Map> = new Map(); private _pendingListChangedConfig?: ListChangedHandlers; + private _enforceStrictCapabilities: boolean; /** * Initializes this client with the given name and version information. @@ -263,6 +264,7 @@ export class Client< super(options); this._capabilities = options?.capabilities ?? {}; this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new AjvJsonSchemaValidator(); + this._enforceStrictCapabilities = options?.enforceStrictCapabilities ?? false; // Store list changed config for setup after connection (when we know server capabilities) if (options?.listChanged) { @@ -705,14 +707,31 @@ export class Client< } async listPrompts(params?: ListPromptsRequest['params'], options?: RequestOptions) { + if (!this._serverCapabilities?.prompts && !this._enforceStrictCapabilities) { + // Respect capability negotiation: server does not support prompts + console.debug('Client.listPrompts() called but server does not advertise prompts capability - returning empty list'); + return { prompts: [] }; + } return this.request({ method: 'prompts/list', params }, ListPromptsResultSchema, options); } async listResources(params?: ListResourcesRequest['params'], options?: RequestOptions) { + if (!this._serverCapabilities?.resources && !this._enforceStrictCapabilities) { + // Respect capability negotiation: server does not support resources + console.debug('Client.listResources() called but server does not advertise resources capability - returning empty list'); + return { resources: [] }; + } return this.request({ method: 'resources/list', params }, ListResourcesResultSchema, options); } async listResourceTemplates(params?: ListResourceTemplatesRequest['params'], options?: RequestOptions) { + if (!this._serverCapabilities?.resources && !this._enforceStrictCapabilities) { + // Respect capability negotiation: server does not support resources + console.debug( + 'Client.listResourceTemplates() called but server does not advertise resources capability - returning empty list' + ); + return { resourceTemplates: [] }; + } return this.request({ method: 'resources/templates/list', params }, ListResourceTemplatesResultSchema, options); } @@ -837,6 +856,11 @@ export class Client< } async listTools(params?: ListToolsRequest['params'], options?: RequestOptions) { + if (!this._serverCapabilities?.tools && !this._enforceStrictCapabilities) { + // Respect capability negotiation: server does not support tools + console.debug('Client.listTools() called but server does not advertise tools capability - returning empty list'); + return { tools: [] }; + } const result = await this.request({ method: 'tools/list', params }, ListToolsResultSchema, options); // Cache the tools and their output schemas for future validation diff --git a/test/integration/test/client/client.test.ts b/test/integration/test/client/client.test.ts index 5574a2d84..af609210d 100644 --- a/test/integration/test/client/client.test.ts +++ b/test/integration/test/client/client.test.ts @@ -595,6 +595,79 @@ test('should respect server capabilities', async () => { ).rejects.toThrow('Server does not support completions'); }); +/*** + * Test: Return empty lists for missing capabilities (default behavior) + * When enforceStrictCapabilities is not set (default), list methods should + * return empty lists instead of sending requests to servers that don't + * advertise those capabilities. + */ +test('should return empty lists for missing capabilities by default', async () => { + const server = new Server( + { + name: 'test server', + version: '1.0' + }, + { + capabilities: { + // Server only supports tools - no prompts or resources + tools: {} + } + } + ); + + server.setRequestHandler(InitializeRequestSchema, _request => ({ + protocolVersion: LATEST_PROTOCOL_VERSION, + capabilities: { + tools: {} + }, + serverInfo: { + name: 'test', + version: '1.0' + } + })); + + server.setRequestHandler(ListToolsRequestSchema, () => ({ + tools: [{ name: 'test-tool', inputSchema: { type: 'object' } }] + })); + + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + + // Client with default settings (enforceStrictCapabilities not set) + const client = new Client( + { + name: 'test client', + version: '1.0' + }, + { + capabilities: {} + } + ); + + await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]); + + // Server only supports tools + expect(client.getServerCapabilities()).toEqual({ + tools: {} + }); + + // listTools should work and return actual tools + const toolsResult = await client.listTools(); + expect(toolsResult.tools).toHaveLength(1); + expect(toolsResult.tools[0].name).toBe('test-tool'); + + // listPrompts should return empty list without sending request + const promptsResult = await client.listPrompts(); + expect(promptsResult.prompts).toEqual([]); + + // listResources should return empty list without sending request + const resourcesResult = await client.listResources(); + expect(resourcesResult.resources).toEqual([]); + + // listResourceTemplates should return empty list without sending request + const templatesResult = await client.listResourceTemplates(); + expect(templatesResult.resourceTemplates).toEqual([]); +}); + /*** * Test: Respect Client Notification Capabilities */ From be703ff164ab513c2f1208527c05b999902054a4 Mon Sep 17 00:00:00 2001 From: Peder Date: Wed, 14 Jan 2026 21:26:46 +0100 Subject: [PATCH 2/3] chore: add changeset for capability negotiation fix Co-Authored-By: Claude Opus 4.5 --- .changeset/respect-capability-negotiation.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .changeset/respect-capability-negotiation.md diff --git a/.changeset/respect-capability-negotiation.md b/.changeset/respect-capability-negotiation.md new file mode 100644 index 000000000..a40ac4e7a --- /dev/null +++ b/.changeset/respect-capability-negotiation.md @@ -0,0 +1,13 @@ +--- +'@modelcontextprotocol/client': patch +--- + +Respect capability negotiation in list methods by returning empty lists when server lacks capability + +The Client now returns empty lists instead of sending requests to servers that don't advertise the corresponding capability: +- `listPrompts()` returns `{ prompts: [] }` if server lacks prompts capability +- `listResources()` returns `{ resources: [] }` if server lacks resources capability +- `listResourceTemplates()` returns `{ resourceTemplates: [] }` if server lacks resources capability +- `listTools()` returns `{ tools: [] }` if server lacks tools capability + +This respects the MCP spec requirement that "Both parties SHOULD respect capability negotiation" and avoids unnecessary server warnings and traffic. The existing `enforceStrictCapabilities` option continues to throw errors when set to `true`. From 657173d696a951161aae0b547c5df72cdf1228b0 Mon Sep 17 00:00:00 2001 From: Peder Date: Thu, 15 Jan 2026 21:28:37 +0100 Subject: [PATCH 3/3] fix(tests): advertise tools capability in outputSchema validation tests These tests were setting up servers with tools capability in the constructor but then returning empty capabilities in the InitializeRequestSchema handler. Now that the client respects capability negotiation, listTools() was returning empty lists since no tools capability was advertised. Fixed by returning { tools: {} } in the InitializeRequestSchema handlers. Co-Authored-By: Claude Opus 4.5 --- test/integration/test/client/client.test.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test/integration/test/client/client.test.ts b/test/integration/test/client/client.test.ts index af609210d..6efa35b44 100644 --- a/test/integration/test/client/client.test.ts +++ b/test/integration/test/client/client.test.ts @@ -1958,7 +1958,7 @@ describe('outputSchema validation', () => { // Set up server handlers server.setRequestHandler(InitializeRequestSchema, async request => ({ protocolVersion: request.params.protocolVersion, - capabilities: {}, + capabilities: { tools: {} }, serverInfo: { name: 'test-server', version: '1.0.0' @@ -2050,7 +2050,7 @@ describe('outputSchema validation', () => { // Set up server handlers server.setRequestHandler(InitializeRequestSchema, async request => ({ protocolVersion: request.params.protocolVersion, - capabilities: {}, + capabilities: { tools: {} }, serverInfo: { name: 'test-server', version: '1.0.0' @@ -2343,7 +2343,7 @@ describe('outputSchema validation', () => { // Set up server handlers server.setRequestHandler(InitializeRequestSchema, async request => ({ protocolVersion: request.params.protocolVersion, - capabilities: {}, + capabilities: { tools: {} }, serverInfo: { name: 'test-server', version: '1.0.0'