Clarify error when mixing call-tool filter styles

Improve the InvalidOperationException thrown when CallToolFilters and
CallToolWithAlternateFilters are both configured, naming the common indirect
cause (combining AddAuthorizationFilters() with WithTasks()) and the current
limitation. Add filter property doc notes and tests.

Author: Tarek Mahmoud Sayed

src/ModelContextProtocol.Core/Server/McpRequestFilters.cs

@@ -43,7 +43,9 @@ public IList<McpRequestFilter<ListToolsRequestParams, ListToolsResult>> ListTool
     /// </para>
     /// <para>
     /// Cannot be used together with <see cref="CallToolWithAlternateFilters"/>. If both are non-empty at configuration time,
-    /// an <see cref="InvalidOperationException"/> will be thrown.
+    /// an <see cref="InvalidOperationException"/> will be thrown. This can happen indirectly when combining features that
+    /// register different tool-call filter styles, such as authorization filters (which use this collection) and the
+    /// tasks extension (which uses <see cref="CallToolWithAlternateFilters"/>).
     /// </para>
     /// </remarks>
     public IList<McpRequestFilter<CallToolRequestParams, CallToolResult>> CallToolFilters
@@ -68,7 +70,9 @@ public IList<McpRequestFilter<CallToolRequestParams, CallToolResult>> CallToolFi
     /// </para>
     /// <para>
     /// Cannot be used together with <see cref="CallToolFilters"/>. If both are non-empty at configuration time,
-    /// an <see cref="InvalidOperationException"/> will be thrown.
+    /// an <see cref="InvalidOperationException"/> will be thrown. This can happen indirectly when combining features that
+    /// register different tool-call filter styles, such as the tasks extension (which uses this collection) and
+    /// authorization filters (which use <see cref="CallToolFilters"/>).
     /// </para>
     /// </remarks>
     public IList<McpRequestFilter<CallToolRequestParams, ResultOrAlternate<CallToolResult>>> CallToolWithAlternateFilters

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -1083,7 +1083,12 @@ private void ConfigureTools(McpServerOptions options)
         {
             throw new InvalidOperationException(
                 $"Cannot mix non-alternate ({nameof(McpServerHandlers.CallToolHandler)}/{nameof(McpRequestFilters.CallToolFilters)}) " +
-                $"with alternate-based ({nameof(McpServerHandlers.CallToolWithAlternateHandler)}/{nameof(McpRequestFilters.CallToolWithAlternateFilters)}). Use one style or the other.");
+                $"with alternate-based ({nameof(McpServerHandlers.CallToolWithAlternateHandler)}/{nameof(McpRequestFilters.CallToolWithAlternateFilters)}) tool-call filters or handlers. " +
+                $"These two styles cannot currently be composed on the same server. " +
+                $"This most commonly happens when combining features that register different tool-call filter styles, " +
+                $"for example AddAuthorizationFilters() (which registers a {nameof(McpRequestFilters.CallToolFilters)} filter) together with " +
+                $"WithTasks() (which registers a {nameof(McpRequestFilters.CallToolWithAlternateFilters)} filter). " +
+                $"Configure only one style, or avoid combining features that require different styles.");
         }
 
         // Handle tools provided via DI by augmenting the list handler.

tests/ModelContextProtocol.Tests/Server/CallToolFilterMixingTests.cs

@@ -0,0 +1,58 @@
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using ModelContextProtocol.Tests.Utils;
+
+namespace ModelContextProtocol.Tests.Server;
+
+/// <summary>
+/// Verifies that combining the non-alternate <see cref="McpRequestFilters.CallToolFilters"/> with the
+/// alternate <see cref="McpRequestFilters.CallToolWithAlternateFilters"/> fails at configuration time
+/// with an actionable message.
+/// </summary>
+public class CallToolFilterMixingTests(ITestOutputHelper testOutputHelper) : LoggedTest(testOutputHelper)
+{
+    private static McpRequestFilter<CallToolRequestParams, CallToolResult> PassThroughCallToolFilter =>
+        next => next;
+
+    private static McpRequestFilter<CallToolRequestParams, ResultOrAlternate<CallToolResult>> PassThroughAlternateFilter =>
+        next => next;
+
+    [Fact]
+    public async Task MixingCallToolFilters_WithAlternateFilters_ThrowsActionableError()
+    {
+        await using var transport = new StreamServerTransport(Stream.Null, Stream.Null);
+        var options = new McpServerOptions { Capabilities = new() { Tools = new() } };
+        options.Filters.Request.CallToolFilters.Add(PassThroughCallToolFilter);
+        options.Filters.Request.CallToolWithAlternateFilters.Add(PassThroughAlternateFilter);
+
+        var ex = Assert.Throws<InvalidOperationException>(
+            () => McpServer.Create(transport, options, LoggerFactory));
+
+        Assert.Contains(nameof(McpRequestFilters.CallToolFilters), ex.Message);
+        Assert.Contains(nameof(McpRequestFilters.CallToolWithAlternateFilters), ex.Message);
+        Assert.Contains("AddAuthorizationFilters", ex.Message);
+        Assert.Contains("WithTasks", ex.Message);
+    }
+
+    [Fact]
+    public async Task CallToolFiltersAlone_Succeeds()
+    {
+        await using var transport = new StreamServerTransport(Stream.Null, Stream.Null);
+        var options = new McpServerOptions { Capabilities = new() { Tools = new() } };
+        options.Filters.Request.CallToolFilters.Add(PassThroughCallToolFilter);
+
+        await using var server = McpServer.Create(transport, options, LoggerFactory);
+        Assert.NotNull(server);
+    }
+
+    [Fact]
+    public async Task AlternateFiltersAlone_Succeeds()
+    {
+        await using var transport = new StreamServerTransport(Stream.Null, Stream.Null);
+        var options = new McpServerOptions { Capabilities = new() { Tools = new() } };
+        options.Filters.Request.CallToolWithAlternateFilters.Add(PassThroughAlternateFilter);
+
+        await using var server = McpServer.Create(transport, options, LoggerFactory);
+        Assert.NotNull(server);
+    }
+}