fix(server): include registered tool icons

Author: Genmin

.changeset/register-tool-icons.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server': patch
+---
+
+Add `icons` support to `McpServer.registerTool()` and task tool registration, and include tool icons in `tools/list` responses.

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';
@@ -21,6 +21,7 @@ interface McpServerInternal {
         description: string | undefined,
         inputSchema: StandardSchemaWithJSON | undefined,
         outputSchema: StandardSchemaWithJSON | undefined,
+        icons: Icon[] | undefined,
         annotations: ToolAnnotations | undefined,
         execution: ToolExecution | undefined,
         _meta: Record<string, unknown> | undefined,
@@ -82,6 +83,7 @@ export class ExperimentalMcpServerTasks {
             title?: string;
             description?: string;
             outputSchema?: OutputArgs;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
@@ -96,6 +98,7 @@ export class ExperimentalMcpServerTasks {
             description?: string;
             inputSchema: InputArgs;
             outputSchema?: OutputArgs;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
@@ -110,6 +113,7 @@ export class ExperimentalMcpServerTasks {
             description?: string;
             inputSchema?: InputArgs;
             outputSchema?: OutputArgs;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             execution?: TaskToolExecution;
             _meta?: Record<string, unknown>;
@@ -130,6 +134,7 @@ export class ExperimentalMcpServerTasks {
             config.description,
             config.inputSchema,
             config.outputSchema,
+            config.icons,
             config.annotations,
             execution,
             config._meta,

packages/server/src/server/mcp.ts

@@ -8,6 +8,7 @@ import type {
     CreateTaskResult,
     CreateTaskServerContext,
     GetPromptResult,
+    Icon,
     Implementation,
     ListPromptsResult,
     ListResourcesResult,
@@ -143,6 +144,7 @@ export class McpServer {
                             name,
                             title: tool.title,
                             description: tool.description,
+                            icons: tool.icons,
                             inputSchema: tool.inputSchema
                                 ? (standardSchemaToJsonSchema(tool.inputSchema, 'input') as Tool['inputSchema'])
                                 : EMPTY_OBJECT_JSON_SCHEMA,
@@ -772,6 +774,7 @@ export class McpServer {
         description: string | undefined,
         inputSchema: StandardSchemaWithJSON | undefined,
         outputSchema: StandardSchemaWithJSON | undefined,
+        icons: Icon[] | undefined,
         annotations: ToolAnnotations | undefined,
         execution: ToolExecution | undefined,
         _meta: Record<string, unknown> | undefined,
@@ -788,6 +791,7 @@ export class McpServer {
             description,
             inputSchema,
             outputSchema,
+            icons,
             annotations,
             execution,
             _meta,
@@ -824,6 +828,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;
@@ -871,6 +876,7 @@ export class McpServer {
             description?: string;
             inputSchema?: InputArgs;
             outputSchema?: OutputArgs;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             _meta?: Record<string, unknown>;
         },
@@ -884,6 +890,7 @@ export class McpServer {
             description?: string;
             inputSchema?: InputArgs;
             outputSchema?: OutputArgs;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             _meta?: Record<string, unknown>;
         },
@@ -896,6 +903,7 @@ export class McpServer {
             description?: string;
             inputSchema?: StandardSchemaWithJSON | ZodRawShape;
             outputSchema?: StandardSchemaWithJSON | ZodRawShape;
+            icons?: Icon[];
             annotations?: ToolAnnotations;
             _meta?: Record<string, unknown>;
         },
@@ -905,14 +913,15 @@ export class McpServer {
             throw new Error(`Tool ${name} is already registered`);
         }
 
-        const { title, description, inputSchema, outputSchema, annotations, _meta } = config;
+        const { title, description, inputSchema, outputSchema, icons, annotations, _meta } = config;
 
         return this._createRegisteredTool(
             name,
             title,
             description,
             normalizeRawShapeSchema(inputSchema),
             normalizeRawShapeSchema(outputSchema),
+            icons,
             annotations,
             { taskSupport: 'forbidden' },
             _meta,
@@ -1162,6 +1171,7 @@ export type RegisteredTool = {
     description?: string;
     inputSchema?: StandardSchemaWithJSON;
     outputSchema?: StandardSchemaWithJSON;
+    icons?: Icon[];
     annotations?: ToolAnnotations;
     execution?: ToolExecution;
     _meta?: Record<string, unknown>;
@@ -1177,6 +1187,7 @@ export type RegisteredTool = {
         description?: string;
         paramsSchema?: StandardSchemaWithJSON;
         outputSchema?: StandardSchemaWithJSON;
+        icons?: Icon[];
         annotations?: ToolAnnotations;
         _meta?: Record<string, unknown>;
         callback?: ToolCallback<StandardSchemaWithJSON>;

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

@@ -1038,6 +1038,57 @@ 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',
+                {
+                    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
          */