Add icons field support to registerTool() and registerToolTask()

The MCP spec's ToolSchema includes icons via IconsSchema, but the
high-level registerTool() and registerToolTask() APIs did not accept
or pass through the icons field. This meant tools/list responses
never included icons even when the spec supports them.

Changes:
- Add icons to RegisteredTool type and update() method
- Add icons parameter to _createRegisteredTool()
- Add icons to registerTool() and registerToolTask() config types
- Include icons in toolDefinition for tools/list responses
- Add test for tool registration with icons

Fixes #1864

Author: Christian-Sidak

packages/server/src/experimental/tasks/mcpServer.ts

@@ -5,7 +5,7 @@
  * @experimental
  */
 
-import type { StandardSchemaWithJSON, TaskToolExecution, ToolAnnotations, ToolExecution } from '@modelcontextprotocol/core';
+import type { Icon, StandardSchemaWithJSON, TaskToolExecution, ToolAnnotations, ToolExecution } from '@modelcontextprotocol/core';
 
 import type { AnyToolHandler, McpServer, RegisteredTool } from '../../server/mcp.js';
 import type { ToolTaskHandler } from './interfaces.js';
@@ -23,6 +23,7 @@ interface McpServerInternal {
         outputSchema: StandardSchemaWithJSON | undefined,
         annotations: ToolAnnotations | undefined,
         execution: ToolExecution | undefined,
+        icons: Icon[] | undefined,
         _meta: Record<string, unknown> | undefined,
         handler: AnyToolHandler<StandardSchemaWithJSON | undefined>
     ): RegisteredTool;
@@ -83,6 +84,7 @@ export class ExperimentalMcpServerTasks {
             description?: string;
             outputSchema?: OutputArgs;
             annotations?: ToolAnnotations;
+            icons?: Icon[];
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
         },
@@ -97,6 +99,7 @@ export class ExperimentalMcpServerTasks {
             inputSchema: InputArgs;
             outputSchema?: OutputArgs;
             annotations?: ToolAnnotations;
+            icons?: Icon[];
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
         },
@@ -111,6 +114,7 @@ export class ExperimentalMcpServerTasks {
             inputSchema?: InputArgs;
             outputSchema?: OutputArgs;
             annotations?: ToolAnnotations;
+            icons?: Icon[];
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
         },
@@ -132,6 +136,7 @@ export class ExperimentalMcpServerTasks {
             config.outputSchema,
             config.annotations,
             execution,
+            config.icons,
             config._meta,
             handler as AnyToolHandler<StandardSchemaWithJSON | undefined>
         );

packages/server/src/server/mcp.ts

@@ -8,6 +8,7 @@ import type {
     CreateTaskResult,
     CreateTaskServerContext,
     GetPromptResult,
+    Icon,
     Implementation,
     ListPromptsResult,
     ListResourcesResult,
@@ -145,6 +146,7 @@ export class McpServer {
                                 ? (standardSchemaToJsonSchema(tool.inputSchema, 'input') as Tool['inputSchema'])
                                 : EMPTY_OBJECT_JSON_SCHEMA,
                             annotations: tool.annotations,
+                            icons: tool.icons,
                             execution: tool.execution,
                             _meta: tool._meta
                         };
@@ -772,6 +774,7 @@ export class McpServer {
         outputSchema: StandardSchemaWithJSON | undefined,
         annotations: ToolAnnotations | undefined,
         execution: ToolExecution | undefined,
+        icons: Icon[] | undefined,
         _meta: Record<string, unknown> | undefined,
         handler: AnyToolHandler<StandardSchemaWithJSON | undefined>
     ): RegisteredTool {
@@ -788,6 +791,7 @@ export class McpServer {
             outputSchema,
             annotations,
             execution,
+            icons,
             _meta,
             handler: handler,
             executor: createToolExecutor(inputSchema, handler),
@@ -822,6 +826,7 @@ export class McpServer {
                 }
 
                 if (updates.outputSchema !== undefined) registeredTool.outputSchema = updates.outputSchema;
+                if (updates.icons !== undefined) registeredTool.icons = updates.icons;
                 if (updates.annotations !== undefined) registeredTool.annotations = updates.annotations;
                 if (updates._meta !== undefined) registeredTool._meta = updates._meta;
                 if (updates.enabled !== undefined) registeredTool.enabled = updates.enabled;
@@ -870,6 +875,7 @@ export class McpServer {
             inputSchema?: InputArgs;
             outputSchema?: OutputArgs;
             annotations?: ToolAnnotations;
+            icons?: Icon[];
             _meta?: Record<string, unknown>;
         },
         cb: ToolCallback<InputArgs>
@@ -878,7 +884,7 @@ export class McpServer {
             throw new Error(`Tool ${name} is already registered`);
         }
 
-        const { title, description, inputSchema, outputSchema, annotations, _meta } = config;
+        const { title, description, inputSchema, outputSchema, annotations, icons, _meta } = config;
 
         return this._createRegisteredTool(
             name,
@@ -888,6 +894,7 @@ export class McpServer {
             outputSchema,
             annotations,
             { taskSupport: 'forbidden' },
+            icons,
             _meta,
             cb as ToolCallback<StandardSchemaWithJSON | undefined>
         );
@@ -1095,6 +1102,7 @@ export type RegisteredTool = {
     inputSchema?: StandardSchemaWithJSON;
     outputSchema?: StandardSchemaWithJSON;
     annotations?: ToolAnnotations;
+    icons?: Icon[];
     execution?: ToolExecution;
     _meta?: Record<string, unknown>;
     handler: AnyToolHandler<StandardSchemaWithJSON | undefined>;
@@ -1110,6 +1118,7 @@ export type RegisteredTool = {
         paramsSchema?: StandardSchemaWithJSON;
         outputSchema?: StandardSchemaWithJSON;
         annotations?: ToolAnnotations;
+        icons?: Icon[];
         _meta?: Record<string, unknown>;
         callback?: ToolCallback<StandardSchemaWithJSON>;
         enabled?: boolean;

test/integration/test/server/mcp.test.ts

@@ -1038,6 +1038,58 @@ describe('Zod v4', () => {
             });
         });
 
+        /***
+         * Test: Tool Registration with Icons
+         */
+        test('should register tool with icons', async () => {
+            const mcpServer = new McpServer({
+                name: 'test server',
+                version: '1.0'
+            });
+            const client = new Client({
+                name: 'test client',
+                version: '1.0'
+            });
+
+            mcpServer.registerTool(
+                'test',
+                {
+                    description: 'A tool with icons',
+                    icons: [
+                        {
+                            src: 'https://example.com/icon.png',
+                            mimeType: 'image/png'
+                        }
+                    ]
+                },
+                async () => ({
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Test response'
+                        }
+                    ]
+                })
+            );
+
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+            await Promise.all([client.connect(clientTransport), mcpServer.server.connect(serverTransport)]);
+
+            const result = await client.request({
+                method: 'tools/list'
+            });
+
+            expect(result.tools).toHaveLength(1);
+            expect(result.tools[0]!.name).toBe('test');
+            expect(result.tools[0]!.icons).toEqual([
+                {
+                    src: 'https://example.com/icon.png',
+                    mimeType: 'image/png'
+                }
+            ]);
+        });
+
         /***
          * Test: Tool Registration with Parameters and Annotations
          */