feat: expose MCP tool annotations for tool grouping (coder#23195)

matifali · web-flow · commit bd5b62c97645 · 2026-03-18T10:21:45.000Z
## Summary - add shared MCP annotation metadata to toolsdk tools - emit MCP tool annotations from both coderd and CLI MCP servers - cover annotation serialization in toolsdk, coderd MCP e2e, and CLI MCP tests ## Why - Coder already exposed MCP tools, but it did not populate MCP tool annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). - Hosts such as Claude Desktop use those hints to classify and group tools, so without them Coder tools can get lumped together. - This change adds a shared annotation source in `toolsdk` and has both MCP servers emit those hints through `mcp.Tool.Annotations`, avoiding drift between local and remote MCP implementations. ## Testing - Tested locally on Cladue Desktop and the tools are categorized correctly. <table> <tr> <td> Before <td> After <tr> <td> <img width="613" height="183" alt="image" src="https://github.com/user-attachments/assets/29d2e3fb-53bc-4ea7-bdb3-f10df4ef996b" /> <td> <img width="600" height="457" alt="image" src="https://github.com/user-attachments/assets/cc384036-c9a7-4db9-9400-43ad51920ff5" /> </table> Note: Done using Coder Agents, reviewed and tested by human locally
diff --git a/cli/exp_mcp.go b/cli/exp_mcp.go
@@ -1000,6 +1000,12 @@ func mcpFromSDK(sdkTool toolsdk.GenericTool, tb toolsdk.Deps) server.ServerTool
 				Properties: sdkTool.Schema.Properties,
 				Required:   sdkTool.Schema.Required,
 			},
+			Annotations: mcp.ToolAnnotation{
+				ReadOnlyHint:    mcp.ToBoolPtr(sdkTool.MCPAnnotations.ReadOnlyHint),
+				DestructiveHint: mcp.ToBoolPtr(sdkTool.MCPAnnotations.DestructiveHint),
+				IdempotentHint:  mcp.ToBoolPtr(sdkTool.MCPAnnotations.IdempotentHint),
+				OpenWorldHint:   mcp.ToBoolPtr(sdkTool.MCPAnnotations.OpenWorldHint),
+			},
 		},
 		Handler: func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			var buf bytes.Buffer
diff --git a/cli/exp_mcp_test.go b/cli/exp_mcp_test.go
@@ -81,7 +81,13 @@ func TestExpMcpServer(t *testing.T) {
 		var toolsResponse struct {
 			Result struct {
 				Tools []struct {
-					Name string `json:"name"`
+					Name        string `json:"name"`
+					Annotations struct {
+						ReadOnlyHint    *bool `json:"readOnlyHint"`
+						DestructiveHint *bool `json:"destructiveHint"`
+						IdempotentHint  *bool `json:"idempotentHint"`
+						OpenWorldHint   *bool `json:"openWorldHint"`
+					} `json:"annotations"`
 				} `json:"tools"`
 			} `json:"result"`
 		}
@@ -94,6 +100,15 @@ func TestExpMcpServer(t *testing.T) {
 		}
 		slices.Sort(foundTools)
 		require.Equal(t, []string{"coder_get_authenticated_user"}, foundTools)
+		annotations := toolsResponse.Result.Tools[0].Annotations
+		require.NotNil(t, annotations.ReadOnlyHint)
+		require.NotNil(t, annotations.DestructiveHint)
+		require.NotNil(t, annotations.IdempotentHint)
+		require.NotNil(t, annotations.OpenWorldHint)
+		assert.True(t, *annotations.ReadOnlyHint)
+		assert.False(t, *annotations.DestructiveHint)
+		assert.True(t, *annotations.IdempotentHint)
+		assert.False(t, *annotations.OpenWorldHint)
 
 		// Call the tool and ensure it works.
 		toolPayload := `{"jsonrpc":"2.0","id":3,"method":"tools/call", "params": {"name": "coder_get_authenticated_user", "arguments": {}}}`
diff --git a/coderd/mcp/mcp.go b/coderd/mcp/mcp.go
@@ -136,6 +136,12 @@ func mcpFromSDK(sdkTool toolsdk.GenericTool, tb toolsdk.Deps) server.ServerTool
 				Properties: sdkTool.Schema.Properties,
 				Required:   sdkTool.Schema.Required,
 			},
+			Annotations: mcp.ToolAnnotation{
+				ReadOnlyHint:    mcp.ToBoolPtr(sdkTool.MCPAnnotations.ReadOnlyHint),
+				DestructiveHint: mcp.ToBoolPtr(sdkTool.MCPAnnotations.DestructiveHint),
+				IdempotentHint:  mcp.ToBoolPtr(sdkTool.MCPAnnotations.IdempotentHint),
+				OpenWorldHint:   mcp.ToBoolPtr(sdkTool.MCPAnnotations.OpenWorldHint),
+			},
 		},
 		Handler: func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			var buf bytes.Buffer
diff --git a/coderd/mcp/mcp_e2e_test.go b/coderd/mcp/mcp_e2e_test.go
@@ -91,21 +91,41 @@ func TestMCPHTTP_E2E_ClientIntegration(t *testing.T) {
 
 	// Verify we have some expected Coder tools
 	var foundTools []string
-	for _, tool := range tools.Tools {
+	var userTool *mcp.Tool
+	var writeFileTool *mcp.Tool
+	for i := range tools.Tools {
+		tool := tools.Tools[i]
 		foundTools = append(foundTools, tool.Name)
+		switch tool.Name {
+		case toolsdk.ToolNameGetAuthenticatedUser:
+			userTool = &tools.Tools[i]
+		case toolsdk.ToolNameWorkspaceWriteFile:
+			writeFileTool = &tools.Tools[i]
+		}
 	}
 
 	// Check for some basic tools that should be available
 	assert.Contains(t, foundTools, toolsdk.ToolNameGetAuthenticatedUser, "Should have authenticated user tool")
-
-	// Find and execute the authenticated user tool
-	var userTool *mcp.Tool
-	for _, tool := range tools.Tools {
-		if tool.Name == toolsdk.ToolNameGetAuthenticatedUser {
-			userTool = &tool
-			break
-		}
-	}
+	require.NotNil(t, userTool)
+	require.NotNil(t, writeFileTool)
+	require.NotNil(t, userTool.Annotations.ReadOnlyHint)
+	require.NotNil(t, userTool.Annotations.DestructiveHint)
+	require.NotNil(t, userTool.Annotations.IdempotentHint)
+	require.NotNil(t, userTool.Annotations.OpenWorldHint)
+	assert.True(t, *userTool.Annotations.ReadOnlyHint)
+	assert.False(t, *userTool.Annotations.DestructiveHint)
+	assert.True(t, *userTool.Annotations.IdempotentHint)
+	assert.False(t, *userTool.Annotations.OpenWorldHint)
+	require.NotNil(t, writeFileTool.Annotations.ReadOnlyHint)
+	require.NotNil(t, writeFileTool.Annotations.DestructiveHint)
+	require.NotNil(t, writeFileTool.Annotations.IdempotentHint)
+	require.NotNil(t, writeFileTool.Annotations.OpenWorldHint)
+	assert.False(t, *writeFileTool.Annotations.ReadOnlyHint)
+	assert.True(t, *writeFileTool.Annotations.DestructiveHint)
+	assert.False(t, *writeFileTool.Annotations.IdempotentHint)
+	assert.False(t, *writeFileTool.Annotations.OpenWorldHint)
+
+	// Execute the authenticated user tool.
 	require.NotNil(t, userTool, "Expected to find "+toolsdk.ToolNameGetAuthenticatedUser+" tool")
 
 	// Execute the tool
diff --git a/codersdk/toolsdk/bash.go b/codersdk/toolsdk/bash.go
@@ -89,6 +89,7 @@ Examples:
 			Required: []string{"workspace", "command"},
 		},
 	},
+	MCPAnnotations: mcpDestructiveAnnotations,
 	Handler: func(ctx context.Context, deps Deps, args WorkspaceBashArgs) (res WorkspaceBashResult, err error) {
 		if args.Workspace == "" {
 			return WorkspaceBashResult{}, xerrors.New("workspace name cannot be empty")
diff --git a/codersdk/toolsdk/chatgpt.go b/codersdk/toolsdk/chatgpt.go
@@ -299,6 +299,7 @@ List workspaces with multiple filters - running workspaces owned by "alice".
 			Required: []string{"query"},
 		},
 	},
+	MCPAnnotations: mcpReadOnlyAnnotations,
 	Handler: func(ctx context.Context, deps Deps, args SearchArgs) (SearchResult, error) {
 		query, err := parseSearchQuery(args.Query)
 		if err != nil {
@@ -419,6 +420,7 @@ var ChatGPTFetch = Tool[FetchArgs, FetchResult]{
 			Required: []string{"id"},
 		},
 	},
+	MCPAnnotations: mcpReadOnlyAnnotations,
 	Handler: func(ctx context.Context, deps Deps, args FetchArgs) (FetchResult, error) {
 		objectID, err := parseObjectID(args.ID)
 		if err != nil {
diff --git a/codersdk/toolsdk/toolsdk.go b/codersdk/toolsdk/toolsdk.go
diff --git a/codersdk/toolsdk/toolsdk_test.go b/codersdk/toolsdk/toolsdk_test.go
