Fix error code usage to align with updated MCP spec guidance

Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

Author: Copilot

docs/concepts/tasks/tasks.md

@@ -424,8 +424,8 @@ Task operations may throw <xref:ModelContextProtocol.McpException> with these er
 
 | Error Code | Scenario |
 |------------|----------|
-| `InvalidParams` | Invalid or nonexistent task ID |
-| `InvalidRequest` | Tool with `taskSupport: forbidden` called with task metadata, or tool with `taskSupport: required` called without task metadata |
+| `InvalidParams` | Invalid or nonexistent task ID, invalid cursor, or attempting to cancel a task already in a terminal status |
+| `InvalidParams` | Tool with `taskSupport: forbidden` called with task metadata, or tool with `taskSupport: required` called without task metadata |
 | `InternalError` | Task execution failure or result unavailable |
 
 Example error handling:

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -461,6 +461,21 @@ private void RegisterTaskHandlers(RequestHandlers requestHandlers, IMcpTaskStore
                     throw new McpProtocolException("Missing required parameter 'taskId'", McpErrorCode.InvalidParams);
                 }
 
+                // Get current task status
+                var currentTask = await taskStore.GetTaskAsync(taskId, SessionId, cancellationToken).ConfigureAwait(false);
+                if (currentTask is null)
+                {
+                    throw new McpProtocolException($"Task not found: '{taskId}'", McpErrorCode.InvalidParams);
+                }
+
+                // Validate not already in terminal status
+                if (currentTask.Status is McpTaskStatus.Completed or McpTaskStatus.Failed or McpTaskStatus.Cancelled)
+                {
+                    throw new McpProtocolException(
+                        $"Cannot cancel task '{taskId}' in terminal status '{currentTask.Status}'.",
+                        McpErrorCode.InvalidParams);
+                }
+
                 // Signal cancellation if task is still running
                 _taskCancellationTokenProvider!.Cancel(taskId);
 

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -591,7 +591,7 @@ await originalListToolsHandler(request, cancellationToken).ConfigureAwait(false)
                         {
                             throw new McpProtocolException(
                                 $"Tool '{tool.ProtocolTool.Name}' does not support task-augmented execution.",
-                                McpErrorCode.MethodNotFound);
+                                McpErrorCode.InvalidParams);
                         }
 
                         // Task augmentation requested - return CreateTaskResult
@@ -604,7 +604,7 @@ await originalListToolsHandler(request, cancellationToken).ConfigureAwait(false)
                         throw new McpProtocolException(
                             $"Tool '{tool.ProtocolTool.Name}' requires task-augmented execution. " +
                             "Include a 'task' parameter with the request.",
-                            McpErrorCode.MethodNotFound);
+                            McpErrorCode.InvalidParams);
                     }
 
                     // Normal synchronous execution
@@ -771,6 +771,21 @@ async Task<JsonElement> GetTaskResultAsync(RequestContext<GetTaskPayloadRequestP
                 throw new McpProtocolException("Missing required parameter 'taskId'", McpErrorCode.InvalidParams);
             }
 
+            // Get current task status
+            var currentTask = await taskStore.GetTaskAsync(taskId, SessionId, cancellationToken).ConfigureAwait(false);
+            if (currentTask is null)
+            {
+                throw new McpProtocolException($"Task not found: '{taskId}'", McpErrorCode.InvalidParams);
+            }
+
+            // Validate not already in terminal status
+            if (currentTask.Status is McpTaskStatus.Completed or McpTaskStatus.Failed or McpTaskStatus.Cancelled)
+            {
+                throw new McpProtocolException(
+                    $"Cannot cancel task '{taskId}' in terminal status '{currentTask.Status}'.",
+                    McpErrorCode.InvalidParams);
+            }
+
             // Signal cancellation if task is still running
             _taskCancellationTokenProvider!.Cancel(taskId);
 

tests/ModelContextProtocol.Tests/Server/McpServerTaskAugmentedValidationTests.cs

@@ -100,7 +100,7 @@ await client.CallToolAsync(
                 TestContext.Current.CancellationToken));
 
         Assert.Contains("does not support task-augmented execution", exception.Message, StringComparison.OrdinalIgnoreCase);
-        Assert.Equal(McpErrorCode.MethodNotFound, exception.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
     }
 
     [Fact]
@@ -227,7 +227,7 @@ await client.CallToolAsync(
                 TestContext.Current.CancellationToken));
 
         Assert.Contains("requires task-augmented execution", exception.Message, StringComparison.OrdinalIgnoreCase);
-        Assert.Equal(McpErrorCode.MethodNotFound, exception.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
     }
 
     [Fact]

tests/ModelContextProtocol.Tests/Server/TaskCancellationIntegrationTests.cs

@@ -460,13 +460,14 @@ public async Task CompletedTask_CannotTransitionToOtherStatus()
 
         Assert.Equal(McpTaskStatus.Completed, taskStatus.Status);
 
-        // Act - Try to cancel a completed task
-        var cancelResult = await client.CancelTaskAsync(taskId, cancellationToken: TestContext.Current.CancellationToken);
+        // Act & Assert - Try to cancel a completed task should throw InvalidParams
+        var exception = await Assert.ThrowsAsync<McpProtocolException>(async () =>
+            await client.CancelTaskAsync(taskId, cancellationToken: TestContext.Current.CancellationToken));
 
-        // Assert - Status should still be completed (not cancelled)
-        Assert.Equal(McpTaskStatus.Completed, cancelResult.Status);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
+        Assert.Contains("terminal status", exception.Message, StringComparison.OrdinalIgnoreCase);
 
-        // Verify via get
+        // Verify task status unchanged
         var verifyStatus = await client.GetTaskAsync(taskId, cancellationToken: TestContext.Current.CancellationToken);
         Assert.Equal(McpTaskStatus.Completed, verifyStatus.Status);
     }
@@ -500,10 +501,11 @@ public async Task FailedTask_CannotTransitionToOtherStatus()
 
         Assert.Equal(McpTaskStatus.Failed, taskStatus.Status);
 
-        // Act - Try to cancel a failed task
-        var cancelResult = await client.CancelTaskAsync(taskId, cancellationToken: TestContext.Current.CancellationToken);
+        // Act & Assert - Try to cancel a failed task should throw InvalidParams
+        var exception = await Assert.ThrowsAsync<McpProtocolException>(async () =>
+            await client.CancelTaskAsync(taskId, cancellationToken: TestContext.Current.CancellationToken));
 
-        // Assert - Status should still be failed
-        Assert.Equal(McpTaskStatus.Failed, cancelResult.Status);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
+        Assert.Contains("terminal status", exception.Message, StringComparison.OrdinalIgnoreCase);
     }
 }

tests/ModelContextProtocol.Tests/Server/ToolTaskSupportTests.cs

@@ -526,8 +526,8 @@ public async Task SyncTool_WithRequiredTaskSupport_CannotBeCalledDirectly()
                 arguments: new Dictionary<string, object?> { ["input"] = "test" },
                 cancellationToken: TestContext.Current.CancellationToken).AsTask());
 
-        // The server returns MethodNotFound because direct invocation is not allowed for required-task tools
-        Assert.Equal(McpErrorCode.MethodNotFound, exception.ErrorCode);
+        // The server returns InvalidParams because direct invocation is not allowed for required-task tools
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
         Assert.Contains("task", exception.Message, StringComparison.OrdinalIgnoreCase);
     }