.NET: ADR: Supporting user approvals

dotnet/Directory.Packages.props

@@ -35,7 +35,8 @@
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.3" />
     <!-- System.* -->
     <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="9.0.8" />
+    <PackageVersion Include="System.Net.Http" Version="4.3.4" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.0-preview.6.25358.103" />
     <PackageVersion Include="System.Text.Json" Version="9.0.8" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="9.0.8" />
     <PackageVersion Include="System.Threading.Channels" Version="9.0.8" />
@@ -47,7 +48,7 @@
     <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
     <!-- Microsoft.Extensions.* -->
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="9.0.8" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.0-preview.6.25358.103" />
     <PackageVersion Include="OpenAI" Version="2.3.0" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="9.8.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="9.8.0-preview.1.25412.6" />
@@ -72,6 +73,8 @@
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.1.151" />
     <!-- Identity -->
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.74.1" />
+    <!-- Other -->
+    <PackageVersion Include="ModelContextProtocol" Version="0.3.0-preview.2" />
     <!-- Test -->
     <PackageVersion Include="FluentAssertions" Version="8.5.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />

dotnet/agent-framework-dotnet.slnx

@@ -128,6 +128,7 @@
     <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime/Microsoft.Extensions.AI.Agents.Runtime.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents/Microsoft.Extensions.AI.Agents.csproj" />
+    <Project Path="src/Microsoft.Extensions.AI.ModelContextProtocol/Microsoft.Extensions.AI.ModelContextProtocol.csproj" Id="4859a869-0c6b-417d-b6d8-6ccbcb60786c" />
   </Folder>
   <Folder Name="/Tests/" />
   <Folder Name="/Tests/Cosmos/">

dotnet/samples/GettingStarted/GettingStarted.csproj

@@ -37,13 +37,15 @@
     <PackageReference Include="xunit" />
     <PackageReference Include="xunit.runner.visualstudio" />
     <PackageReference Include="System.Linq.Async" />
+    <PackageReference Include="System.Net.Http" />
   </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\..\src\Microsoft.Agents.Orchestration\Microsoft.Agents.Orchestration.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents.AzureAI\Microsoft.Extensions.AI.Agents.AzureAI.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents.OpenAI\Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
+    <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.ModelContextProtocol\Microsoft.Extensions.AI.ModelContextProtocol.csproj" />
   </ItemGroup>
 
   <ItemGroup>

dotnet/samples/GettingStarted/Steps/Step10_ChatClientAgent_UsingFunctionToolsWithApprovals.cs

@@ -1,8 +1,13 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.ComponentModel;
+#if NETFRAMEWORK
+using System.Net.Http;
+#endif
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.AI.Agents;
+using Microsoft.Extensions.AI.ModelContextProtocol;
+using Microsoft.Extensions.DependencyInjection;
 
 namespace Steps;
 
@@ -32,7 +37,12 @@ public async Task ApprovalsWithTools(ChatClientProviders provider)
             tools: [
                 new ApprovalRequiredAIFunction(AIFunctionFactory.Create(menuTools.GetMenu)),
                 new ApprovalRequiredAIFunction(AIFunctionFactory.Create(menuTools.GetSpecials)),
-                AIFunctionFactory.Create(menuTools.GetItemPrice)
+                AIFunctionFactory.Create(menuTools.GetItemPrice),
+                new HostedMcpServerTool("Tiktoken Documentation", new Uri("https://gitmcp.io/openai/tiktoken"))
+                {
+                    AllowedTools = ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
+                    ApprovalMode = HostedMcpServerToolApprovalMode.AlwaysRequire,
+                }
             ]);
 
         // Create the server-side agent Id when applicable (depending on the provider).
@@ -41,15 +51,34 @@ public async Task ApprovalsWithTools(ChatClientProviders provider)
         // Get the chat client to use for the agent.
         using var chatClient = base.GetChatClient(provider, agentOptions);
 
+        // Modify the chat client to include MCP and built-in approvals if not already present.
+        var chatBuilder = chatClient.AsBuilder();
+        if (chatClient.GetService<HostedMCPChatClient>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new HostedMCPChatClient(innerClient, new HttpClient());
+            });
+        }
+        if (chatClient.GetService<NewFunctionInvokingChatClient>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new NewFunctionInvokingChatClient(innerClient, null, services);
+            });
+        }
+        using var chatClientWithMCPAndApprovals = chatBuilder.Build();
+
         // Define the agent
-        var agent = new ChatClientAgent(chatClient, agentOptions);
+        var agent = new ChatClientAgent(chatClientWithMCPAndApprovals, agentOptions);
 
         // Create the chat history thread to capture the agent interaction.
         var thread = agent.GetNewThread();
 
         // Respond to user input, invoking functions where appropriate.
         await RunAgentAsync("What is the special soup and its price?");
         await RunAgentAsync("What is the special drink?");
+        await RunAgentAsync("how does tiktoken work?");
 
         async Task RunAgentAsync(string input)
         {
@@ -63,7 +92,7 @@ async Task RunAgentAsync(string input)
                 // Approve GetSpecials function calls, reject all others.
                 List<ChatMessage> nextIterationMessages = userInputRequests?.Select((request) => request switch
                 {
-                    FunctionApprovalRequestContent functionApprovalRequest when functionApprovalRequest.FunctionCall.Name == "GetSpecials" =>
+                    FunctionApprovalRequestContent functionApprovalRequest when functionApprovalRequest.FunctionCall.Name == "GetSpecials" || functionApprovalRequest.FunctionCall.Name == "add" || functionApprovalRequest.FunctionCall.Name == "search_tiktoken_documentation" =>
                         new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(approved: true)]),
 
                     FunctionApprovalRequestContent functionApprovalRequest =>
@@ -110,6 +139,11 @@ public async Task ApprovalsWithToolsStreaming(ChatClientProviders provider)
                 new ApprovalRequiredAIFunction(AIFunctionFactory.Create(menuTools.GetMenu)),
                 new ApprovalRequiredAIFunction(AIFunctionFactory.Create(menuTools.GetSpecials)),
                 AIFunctionFactory.Create(menuTools.GetItemPrice),
+                new HostedMcpServerTool("Tiktoken Documentation", new Uri("https://gitmcp.io/openai/tiktoken"))
+                {
+                    AllowedTools = ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
+                    ApprovalMode = HostedMcpServerToolApprovalMode.AlwaysRequire,
+                }
             ]);
 
         // Create the server-side agent Id when applicable (depending on the provider).
@@ -118,15 +152,34 @@ public async Task ApprovalsWithToolsStreaming(ChatClientProviders provider)
         // Get the chat client to use for the agent.
         using var chatClient = base.GetChatClient(provider, agentOptions);
 
+        // Modify the chat client to include MCP and built-in approvals if not already present.
+        var chatBuilder = chatClient.AsBuilder();
+        if (chatClient.GetService<HostedMCPChatClient>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new HostedMCPChatClient(innerClient, new HttpClient());
+            });
+        }
+        if (chatClient.GetService<NewFunctionInvokingChatClient>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new NewFunctionInvokingChatClient(innerClient, null, services);
+            });
+        }
+        using var chatClientWithMCPAndApprovals = chatBuilder.Build();
+
         // Define the agent
-        var agent = new ChatClientAgent(chatClient, agentOptions);
+        var agent = new ChatClientAgent(chatClientWithMCPAndApprovals, agentOptions);
 
         // Create the chat history thread to capture the agent interaction.
         var thread = agent.GetNewThread();
 
         // Respond to user input, invoking functions where appropriate.
         await RunAgentAsync("What is the special soup and its price?");
         await RunAgentAsync("What is the special drink?");
+        await RunAgentAsync("how does tiktoken work?");
 
         async Task RunAgentAsync(string input)
         {
@@ -140,7 +193,7 @@ async Task RunAgentAsync(string input)
                 // Approve GetSpecials function calls, reject all others.
                 List<ChatMessage> nextIterationMessages = userInputRequests?.Select((request) => request switch
                 {
-                    FunctionApprovalRequestContent functionApprovalRequest when functionApprovalRequest.FunctionCall.Name == "GetSpecials" =>
+                    FunctionApprovalRequestContent functionApprovalRequest when functionApprovalRequest.FunctionCall.Name == "GetSpecials" || functionApprovalRequest.FunctionCall.Name == "add" || functionApprovalRequest.FunctionCall.Name == "search_tiktoken_documentation" =>
                         new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(approved: true)]),
 
                     FunctionApprovalRequestContent functionApprovalRequest =>

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerTool.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a hosted MCP server tool that can be specified to an AI service.
+/// </summary>
+public class HostedMcpServerTool : AITool
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedMcpServerTool"/> class.
+    /// </summary>
+    /// <param name="serverName">The name of the remote MCP server.</param>
+    /// <param name="url">The URL of the remote MCP server.</param>
+    public HostedMcpServerTool(string serverName, Uri url)
+    {
+        ServerName = Throw.IfNullOrWhitespace(serverName);
+        Url = Throw.IfNull(url);
+    }
+
+    /// <summary>
+    /// Gets the name of the remote MCP server that is used to identify it.
+    /// </summary>
+    public string ServerName { get; }
+
+    /// <summary>
+    /// Gets the URL of the remote MCP server.
+    /// </summary>
+    public Uri Url { get; }
+
+    /// <summary>
+    /// Gets or sets the description of the remote MCP server, used to provide more context to the AI service.
+    /// </summary>
+    public string? ServerDescription { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of tools allowed to be used by the AI service.
+    /// </summary>
+    public IList<string>? AllowedTools { get; set; }
+
+    /// <summary>
+    /// Gets or sets the approval mode that indicates when the AI service should require user approval for tool calls to the remote MCP server.
+    /// </summary>
+    /// <remarks>
+    /// You can set this property to <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to require approval for all tool calls,
+    /// or to <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to never require approval.
+    /// </remarks>
+    public HostedMcpServerToolApprovalMode? ApprovalMode { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTP headers that the AI service should use when making tool calls to the remote MCP server.
+    /// </summary>
+    /// <remarks>
+    /// This property is useful for specifying the authentication header or other headers required by the MCP server.
+    /// </remarks>
+    public IDictionary<string, string>? Headers { get; set; }
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerToolAlwaysRequireApprovalMode.cs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Indicates that approval is always required for tool calls to a hosted MCP server.
+/// </summary>
+/// <remarks>
+/// Use <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to get an instance of <see cref="HostedMcpServerToolAlwaysRequireApprovalMode"/>.
+/// </remarks>
+[DebuggerDisplay(nameof(AlwaysRequire))]
+public sealed class HostedMcpServerToolAlwaysRequireApprovalMode : HostedMcpServerToolApprovalMode;

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerToolApprovalMode.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Describes how approval is required for tool calls to a hosted MCP server.
+/// </summary>
+/// <remarks>
+/// The predefined values <see cref="AlwaysRequire" />, and <see cref="NeverRequire"/> are provided to specify handling for all tools.
+/// To specify approval behavior for individual tool names, use <see cref="RequireSpecific(IList{string}, IList{string})"/>.
+/// </remarks>
+#pragma warning disable CA1052 // Static holder types should be Static or NotInheritable
+public class HostedMcpServerToolApprovalMode
+#pragma warning restore CA1052
+{
+    /// <summary>
+    /// Gets a predefined <see cref="HostedMcpServerToolApprovalMode"/> indicating that all tool calls to a hosted MCP server always require approval.
+    /// </summary>
+    public static HostedMcpServerToolAlwaysRequireApprovalMode AlwaysRequire { get; } = new();
+
+    /// <summary>
+    /// Gets a predefined <see cref="HostedMcpServerToolApprovalMode"/> indicating that all tool calls to a hosted MCP server never require approval.
+    /// </summary>
+    public static HostedMcpServerToolNeverRequireApprovalMode NeverRequire { get; } = new();
+
+    private protected HostedMcpServerToolApprovalMode()
+    {
+    }
+
+    /// <summary>
+    /// Instantiates a <see cref="HostedMcpServerToolApprovalMode"/> that specifies approval behavior for individual tool names.
+    /// </summary>
+    /// <param name="alwaysRequireApprovalToolNames">The list of tools names that always require approval.</param>
+    /// <param name="neverRequireApprovalToolNames">The list of tools names that never require approval.</param>
+    /// <returns>An instance of <see cref="HostedMcpServerToolRequireSpecificApprovalMode"/> for the specified tool names.</returns>
+    public static HostedMcpServerToolRequireSpecificApprovalMode RequireSpecific(IList<string>? alwaysRequireApprovalToolNames, IList<string>? neverRequireApprovalToolNames)
+        => new(alwaysRequireApprovalToolNames, neverRequireApprovalToolNames);
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerToolNeverRequireApprovalMode .cs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Indicates that approval is never required for tool calls to a hosted MCP server.
+/// </summary>
+/// <remarks>
+/// Use <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to get an instance of <see cref="HostedMcpServerToolNeverRequireApprovalMode"/>.
+/// </remarks>
+[DebuggerDisplay(nameof(NeverRequire))]
+public sealed class HostedMcpServerToolNeverRequireApprovalMode : HostedMcpServerToolApprovalMode;

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerToolRequireSpecificApprovalMode .cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a mode where approval behavior is specified for individual tool names.
+/// </summary>
+public sealed class HostedMcpServerToolRequireSpecificApprovalMode : HostedMcpServerToolApprovalMode
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedMcpServerToolRequireSpecificApprovalMode"/> class that specifies approval behavior for individual tool names.
+    /// </summary>
+    /// <param name="alwaysRequireApprovalToolNames">The list of tools names that always require approval.</param>
+    /// <param name="neverRequireApprovalToolNames">The list of tools names that never require approval.</param>
+    public HostedMcpServerToolRequireSpecificApprovalMode(IList<string>? alwaysRequireApprovalToolNames, IList<string>? neverRequireApprovalToolNames)
+    {
+        AlwaysRequireApprovalToolNames = alwaysRequireApprovalToolNames;
+        NeverRequireApprovalToolNames = neverRequireApprovalToolNames;
+    }
+
+    /// <summary>
+    /// Gets or sets the list of tool names that always require approval.
+    /// </summary>
+    public IList<string>? AlwaysRequireApprovalToolNames { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of tool names that never require approval.
+    /// </summary>
+    public IList<string>? NeverRequireApprovalToolNames { get; set; }
+}