利用MCP創建AI代理：C# 實踐指南

作者：晶顏 2025-10-31 10:26:40

本文提供了一份基于模型上下文協議（MCP）與C#開發人工智能代理的實踐教程。

譯者 | 晶顏

審校 | 重樓

大型語言模型（LLMs）的快速演進已對人工智能應用領域產生顛覆性影響，其核心優勢在于具備自然語言理解與生成能力及邏輯推理能力。然而，LLMs仍存在顯著局限性：無法訪問實時數據源，亦不能調用外部計算工具。這種“信息孤立”狀態使其無法提供實時更新的信息，同時限制了其在動態系統中的適配能力及文本生成之外的任務執行能力。

當前行業針對該問題的解決方案，要求開發人員為每個數據源或工具單獨構建應用連接，導致系統結構復雜，不僅難以實現管理、擴展，也無法在不同AI應用間形成標準化體系。無論是通信協議、認證機制還是數據轉換邏輯，均需針對每個集成項目開展定制化開發，最終造成開發成本高企、跨系統兼容性不足等問題。

模型上下文協議（MCP）通過通用接口標準有效解決了上述痛點，為AI系統與外部資源的連接提供了標準化方案。其運作邏輯可簡化為：構建“AI應用的USB-C接口”，使所有符合MCP標準的客戶端，無需掌握具體實現細節，即可與任意符合MCP標準的服務器建立連接。

憑借標準化特性，MCP為開發人員構建AI代理提供了多重核心優勢：其一，所有連接的API層面保持一致性，大幅簡化多數據源集成流程；其二，標準化的認證與授權機制，提升系統安全性與隱私控制能力；其三，標準化特性支持開發可復用組件，供不同組織及各類AI應用靈活調用。

MCP的價值不僅限于功能可用性層面。基于其標準協議，可構建完善的生態系統，使AI代理在不同工具與數據源之間切換時，無需擔心上下文與狀態丟失。而開發需執行復雜多步驟任務的AI代理，恰恰需要具備與多系統交互的能力，MCP的這一特性為此類開發提供了關鍵支撐。

C#編程語言和.NET生態系統為基于MCP的AI代理開發提供了最佳基礎。由Anthropic與微軟聯合開發的官方C# SDK，充分利用現代.NET應用的依賴注入、托管及配置功能。這種深度集成使開發人員能夠構建可擴展、易維護的AI代理，且該類代理可適配多種部署環境，從本地開發機器到云端生產系統均能穩定運行。

本文為C#環境下基于MCP的AI代理開發與部署提供了詳盡指南，內容涵蓋協議架構解析、實現模式研究，以及如何依托MCP功能開發滿足安全、性能及維護要求的高效AI代理。

模型上下文協議基礎原理

模型上下文協議（MCP）的架構設計基于業界廣泛認可的通信標準與設計原則，核心目標是實現系統間的互操作性、安全性與可擴展性。MCP采用JSON-RPC 2.0作為消息格式，為客戶端與服務器間的遠程過程調用提供高效且可靠的框架。協議設計過程中，未選擇開發全新通信方式，而是優先采用已成熟驗證的技術，確保協議穩定性與兼容性。

MCP采用客戶端-服務器架構模式：AI應用程序（主機）運行MCP客戶端，客戶端與MCP服務器建立連接；服務器通過資源、工具、提示等各類功能，向已連接的客戶端開放服務能力。系統組件呈現非對稱結構特征：客戶端主動發起連接流程，隨后向服務器發送請求；服務器僅響應客戶端請求，并可選擇性對請求進行采樣處理。

MCP借鑒了語言服務器協議（LSP）的核心設計理念——LSP已在軟件開發生態中實現編程語言服務與開發工具交互的標準化。與LSP類似，MCP支持任意AI應用通過標準化接口連接至任意數據源或工具，打破了傳統開發中的“接口壁壘”。

能力協商是MCP架構的關鍵機制，旨在保障客戶端與服務器間的兼容性。連接建立初期，雙方會執行握手流程，交換能力信息并明確各自可提供的功能。這一機制確保即便客戶端與服務器的功能集、版本或能力存在差異，系統仍能保持穩定連接。

安全與信任是MCP架構設計的核心考量因素。鑒于MCP支持任意數據訪問與代碼執行，具備強大功能拓展性，因此對用戶授權、數據隱私及工具安全性提出了嚴格要求。安全設計貫穿協議架構全流程，為基于MCP的系統在生產環境中的安全部署提供了底層保障。

核心組件與功能特性

MCP系統由多個關鍵組件構成，各組件協同工作，實現AI系統與外部資源的深度整合。開發基于MCP的AI代理，需首先深入理解這些核心組件的功能與作用機制。

資源組件

資源是MCP系統中的核心數據訪問載體。通過資源組件，服務器可向AI模型及用戶提供標準化的內容與關聯背景信息。每個資源均具備唯一URI，用于身份標識，且可承載從基礎文本文件到復雜結構化信息等各類內容。資源抽象機制使服務器能夠實現數據分發，而無需客戶端掌握數據存儲方式或訪問協議，降低了客戶端開發復雜度。

根據內容特性，資源可分為兩類：

靜態資源：包含長期穩定、極少變更的內容，如文檔、配置文件等；
動態資源：內容會根據當前系統數據及外部環境因素實時生成，支持AI代理整合實時信息。

憑借資源組件的靈活性，MCP服務器可作為AI系統與實時數據庫、API、監控系統等外部資源的數據橋梁，實現多源數據的高效對接。

行動導向組件

MCP的行動導向組件包含能夠使AI模型在連接的系統中運行功能并執行操作的工具。工具定義需包含完整架構細節，明確輸入參數要求、預期輸出結果及行為描述。基于標準化架構定義，AI模型可準確理解工具使用方式，同時保障類型安全性與操作可驗證性。

系統安全與用戶管理是MCP工具執行機制的核心設計原則：工具調用前需獲得用戶明確授權，協議支持用戶在工具運行前核查其使用范圍與權限。這種設計使AI代理能夠執行復雜自動化任務，同時有效防范未授權操作風險。

提示組件

提示組件使服務器能夠向AI應用提供預置的通信模板與流程模板。與主要為AI模型提供數據支持的資源、工具不同，提示組件的核心作用是通過為任務與查詢提供結構化模板，支撐人機交互過程。這些模板包含可自定義參數，參數值可從當前上下文自動獲取。

借助提示組件，開發人員可構建可復用的交互模式，適配各類AI應用場景。對于需建立標準化AI交互流程，或為缺乏最優提示策略的用戶提供分步指導的組織而言，該組件的價值尤為突出。

傳輸層與通信機制

MCP的傳輸層為客戶端與服務器間的通信提供基礎支撐，支持多種傳輸機制，以適配不同部署場景與業務需求。協議采用“傳輸無關”設計理念，確保相同應用邏輯可在各類通信通道中直接運行，無需修改代碼。

標準輸入/輸出（stdio）傳輸

stdio是MCP實現中最常用的傳輸機制，其核心優勢在于依托各操作系統與編程環境中均具備的標準輸入/輸出流，實現廣泛兼容性。該傳輸方式尤其適用于本地開發場景，以及MCP服務器作為獨立進程部署、且由客戶端應用程序啟動和管理的場景。

在開發與測試階段，stdio傳輸具備顯著優勢：通過標準日志機制實現便捷調試；支持進程生命周期的簡化管理；配置需求極低；同時天然實現進程隔離，避免服務器故障直接影響客戶端應用程序運行。

HTTP傳輸

HTTP傳輸機制將MCP的應用范圍拓展至分布式系統與網絡化部署場景。通過支持標準HTTP協議，MCP服務器可作為網絡服務部署，實現任意聯網客戶端的訪問。這種傳輸方式使“共享MCP服務器（為多客戶端應用提供服務）”、“云端部署（服務器與客戶端處于不同環境）”等場景成為可能。

HTTP傳輸引入了額外的認證、授權及網絡安全考量，MCP通過可擴展頭部機制及對標準HTTP安全實踐的支持，滿足上述安全需求；同時，協議還定義了針對HTTP特有問題（如連接池管理、超時控制、錯誤處理）的解決方案。

服務器推送事件（SSE）傳輸

SSE傳輸采用混合策略，融合了HTTP通信的優勢與實時流傳輸能力。該機制支持服務器主動向客戶端推送更新，無需客戶端持續輪詢，因此特別適用于實時數據流處理、長時間運行操作等場景。

對于需實時感知外部條件變化、或接收相關事件通知的AI代理而言，SSE傳輸的價值尤為顯著。它使開發更具響應性與情境感知能力的AI系統成為可能——此類系統可在無需用戶手動干預的情況下，自動對外部環境變化做出反應。

圖1：模型上下文協議架構圖，展示了主機之間的關系：通過協議層與客戶端、服務器以及外部系統進行通信

C# SDK實現與架構

針對模型上下文協議（MCP）的官方C#開發工具包（SDK），實現了協議的完整功能，并深度融合.NET生態系統的技術特性。該SDK由Anthropic與微軟聯合開發，以三個獨立軟件包的形式提供，適配不同應用場景的開發與部署需求。

ModelContextProtocol包：作為大多數應用的核心入口，集成了托管擴展、依賴注入能力及符合現代.NET開發標準的高級抽象。該包與微軟“Hosted”框架無縫兼容，支持開發人員通過標準化模式與約定創建MCP服務器和客戶端。
ModelContextProtocol.Core包：為僅需基礎依賴或需直接操作底層協議的應用提供精簡版本。包含核心的客戶端/服務器API、協議類型定義及傳輸抽象，但不含托管與依賴注入功能，可適配從簡單控制臺應用到復雜分布式系統的多類部署場景。
ModelContextProtocol.AspNetCore包：為ASP.NET Core應用提供基于HTTP的MCP服務器功能，包含中間件、路由擴展及服務器推送事件（SSE）支持，使MCP服務器可作為網絡服務運行。通過與ASP.NET Core管道的集成，MCP服務器能直接復用框架內置的認證授權、日志監控等能力。

SDK的模塊化設計展示了一種經過深思熟慮的軟件開發方法，兼顧了易用性與適應性。開發人員可根據需求選擇組件，確保應用僅包含必要依賴，有效降低云原生環境下的資源占用與啟動耗時，符合輕量化部署要求。

依賴注入與服務配置

C# SDK與微軟依賴注入框架的深度整合，是其核心架構優勢之一。這種整合允許開發人員復用在其他.NET應用中的開發模式與實踐經驗，降低學習成本并提升代碼可維護性。具體特性如下：

無縫集成配置：SDK提供與 IServiceCollection 接口無縫對接的擴展方法，支持MCP服務器、客戶端與其他應用服務協同配置，可實現外部服務注入MCP工具、多傳輸機制配置、自定義認證授權邏輯等復雜場景。
自動化服務注冊：采用流暢配置模式，支持開發人員精準定義MCP服務器需暴露的功能。例如， WithToolsFromAssembly() 方法通過反射自動發現并注冊帶有 McpServerTool 屬性的方法，無需手動操作且保持類型安全。
便捷測試支持：MCP工具與資源均以服務形式注冊，在單元測試中可輕松模擬或替換為測試實現，使AI代理能脫離外部依賴獨立完成驗證，為構建可靠、可測試的系統提供保障。

傳輸層實現

C# SDK的傳輸層功能為MCP接口提供抽象化通信方案，確保相同應用邏輯無需修改即可適配多種傳輸類型，提升部署與集成的靈活性。

標準輸入輸出（stdio）傳輸基于各環境通用的標準輸入輸出流，構建基礎且高效的通信系統。SDK封裝了進程管理、流緩沖、錯誤處理等底層操作，為開發人員提供簡潔接口，適用于本地開發環境及獨立進程式MCP服務器部署場景。

該傳輸實現具備完善的錯誤檢測與恢復機制：通信異常時，SDK會輸出具體錯誤信息并嘗試重連，以可靠性為核心設計目標，保障系統在生產環境中的穩定運行。

HTTP傳輸實現使MCP能夠在分布式環境以及網絡部署中運行。該軟件開發工具包依托ASP.NET Core的HTTP處理能力，構建強大可擴展的分布式通信基礎，支持壓縮、緩存、連接池化等標準HTTP功能，適配分布式環境與網絡部署場景。

針對網絡型AI代理部署的特定需求，該實現支持跨源資源共享（CORS），生產環境可復用標準HTTP認證機制；同時整合ASP.NET Core內置可觀測性特性，提供完整的日志與監控功能。

服務器推送事件（SSE）傳輸融合了HTTP通信優勢與實時流傳輸能力，尤其適用于需監測外部條件、接收事件通知的智能代理。

C# SDK 通過其 SSE 實現方式處理了長期連接的復雜性，為開發者提供了一種簡便的編程模型。該SDK會自動維護連接生命周期、保障客戶端平穩斷開，并支持向多連接客戶端廣播更新，降低實時通信功能的開發難度。

圖 2：MCP通信流程圖，展示了各組件之間交互的順序

實際應用示例

本示例旨在闡釋使用 C# SDK 構建 MCP 服務器的核心概念，通過簡潔的配置流程，實現一個可正常運行的 MCP 服務器，并向連接的客戶端提供可用工具。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;
namespace MCPExamples
{
  public class Program
  {
    public static async Task Main(string[] args)
    {
        var builder = Host.CreateApplicationBuilder(args);
        // Configure logging to stderr for MCP compatibility
        builder.Logging.AddConsole(consoleLogOptions =>
        {
        consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
        });
        // Configure MCP server with stdio transport and tool discovery
        builder.Services
        .AddMcpServer()
        .WithStdioServerTransport()
        .WithToolsFromAssembly();
        await builder.Build().RunAsync();
     }
  }
  [McpServerToolType]
  public static class BasicTools
	{
        [McpServerTool, Description("Echoes the provided message back to the
        client")]
        public static string Echo(
        [Description("The message to echo back")] string message)
        {
          return $"Echo: {message}";
        }
        [McpServerTool, Description("Calculates the length of the provided
        text")]
        public static int TextLength(
        [Description("The text to measure")] string text)
        {
          return text?.Length ?? 0;
        }
    }
}

此基本實現展示了幾個關鍵概念。Host.CreateApplicationBuilder() 方法創建了一個包含依賴注入、配置和日志功能的.NET 應用程序。其中日志定向至標準錯誤流，是因標準輸出流被協議通信獨占，避免二者沖突。

AddMcpServer() 擴展方法為 MCP 服務器功能提供了必要的服務，而WithStdioServerTransport()則配置服務器以使用標準輸入/輸出進行通信。WithToolsFromAssembly() 方法開啟工具自動發現機制，無需手動注冊，SDK會自動識別帶有指定屬性的工具方法。

該工具的實現展示了如何通過屬性來展示功能：類通過 [McpServerToolType] 屬性標識為“MCP工具容器”；單個方法通過 [McpServerTool] 屬性成為可被調用的工具；[Description] 屬性提供可讀說明，幫助AI模型理解工具的功能及參數用途，提升交互適配性。

支持外部服務集成的高級服務器示例

大多數復雜的MCP服務器通常需與外部數據庫、服務及API對接。本示例展示如何通過依賴注入實現外部服務訪問，并實現MCP專屬邏輯與業務邏輯的解耦。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;
using System.ComponentModel;
using System.Text.Json;
namespace MCPExamples.Advanced
{
  public class Program
  {
    public static async Task Main(string[] args)
    {
      var builder = Host.CreateApplicationBuilder(args);
      // Register external services
      builder.Services.AddHttpClient();
      builder.Services.AddSingleton<IWeatherService, WeatherService>();
      builder.Services.AddSingleton<IDataAnalysisService,
      DataAnalysisService>();
      builder.Services
      .AddMcpServer()
      .WithStdioServerTransport()
      .WithToolsFromAssembly()
      .WithPromptsFromAssembly();
      await builder.Build().RunAsync();
    }
  }
  [McpServerToolType]
  public static class AdvancedTools
    {
      [McpServerTool, Description("Gets current weather information for a
      specified location")]
      public static async Task<string> GetWeather(
      IWeatherService weatherService,
      [Description("The location to get weather for")] string location)
      {
        var weather = await weatherService.GetWeatherAsync(location);
        return JsonSerializer.Serialize(weather, new JsonSerializerOptions
        { WriteIndented = true });
      }
      [McpServerTool, Description("Performs statistical analysis on numerical
      data")]
      public static async Task<string> AnalyzeData(
      IDataAnalysisService analysisService,
      [Description("Array of numerical values to analyze")] double[]
      data)
      {
        var analysis = await analysisService.AnalyzeDataAsync(data);
        var report = await analysisService.GenerateReportAsync(analysis);
        return report;
      }
   }
}

該高級示例呈現了構建生產級MCP服務器的核心設計模式。通過對 IWeatherService （天氣服務）與 IDataAnalysisService （數據分析服務）等外部服務實施依賴注入，實現了MCP專屬邏輯與業務邏輯的徹底解耦。這種代碼分離架構提高了可測試性和可維護性，并允許在不同的環境中重復使用業務邏輯。

基于接口定義外部服務的設計，支持開發人員在單元測試中用模擬實現替換真實服務，輕松構建復雜測試場景。這種方式對開發獨立驗證功能、無外部依賴的高可靠AI代理至關重要，是保障生產級系統穩定性的關鍵實踐。

客戶端實現與集成模式

MCP客戶端是AI應用與MCP服務器建立連接、實現通信的核心組件。以下內容詳細說明完整MCP客戶端的構建邏輯，及其如何檢測并調用服務器功能。

using ModelContextProtocol;
using ModelContextProtocol.Client;
using Microsoft.Extensions.AI;
using System.Text.Json;
namespace MCPExamples.Client
{
  public class MCPClientExample
  {
    private IMcpClient? _client;
    public async Task<bool> ConnectToServerAsync(string serverCommand,
    string[] arguments)
    {
    try
      {
        var clientTransport = new StdioClientTransport(new
        StdioClientTransportOptions
        {
        Name = "ExampleClient",
        Command = serverCommand,
        Arguments = arguments
        });
        _client = await McpClientFactory.CreateAsync(clientTransport);
        return true;
      }
      catch (Exception ex)
      {
        Console.WriteLine($"Failed to connect to server:
        {ex.Message}");
        return false;
      }
    }
    public async Task<string?> ExecuteToolAsync(string toolName,
    Dictionary<string, object?> arguments)
    {
      if (_client == null) return null;
      try
      {
        var result = await _client.CallToolAsync(toolName, arguments,
        CancellationToken.None);
        var textContent = result.Content.FirstOrDefault(c => c.Type ==
        "text");
        return textContent?.Text;
      }
      catch (Exception ex)
      {
        Console.WriteLine($"Error executing tool {toolName}:
        {ex.Message}");
        return null;
      }
    }
  }
}

客戶端實現封裝了MCP服務器連接與交互的標準化模式，核心流程如下：

傳輸配置定義： StdioClientTransport 配置項同時指定服務器進程的啟動方式與通信協議，為客戶端與服務器的底層通信提供基礎參數；
連接與能力協商： McpClientFactory.CreateAsync() 方法負責完成服務器連接的建立，并自動執行客戶端與服務器的能力協商，確保雙方功能兼容；
工具調用與結果處理： ExecuteToolAsync() 方法定義了服務器工具的調用流程，包含工具啟動、結果解析及錯誤處理。其完善的錯誤處理機制，可幫助客戶端有效應對服務器故障、通信中斷等異常場景，保障交互穩定性。

ASP.NET Core HTTP 服務器實現

ASP.NET Core 這個軟件包提供了基于 HTTP 的完整 MCP 服務器支持，適用于需要進行基于Web部署或與現有Web應用程序集成的場景。

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using ModelContextProtocol.AspNetCore;
using ModelContextProtocol.Server;
namespace MCPExamples.AspNetCore
{
  public class Program
  {
    public static void Main(string[] args)
    {
      var builder = WebApplication.CreateBuilder(args);
      // Configure services
      builder.Services.AddHttpClient();
      builder.Services.AddSingleton<IDocumentService, DocumentService>();
      // Configure MCP server with HTTP transport
      builder.Services
      .AddMcpServer()
      .WithHttpServerTransport()
      .WithToolsFromAssembly();
      // Add CORS for web client access
      builder.Services.AddCors(options =>
      {
      options.AddDefaultPolicy(policy =>
      {
      policy.AllowAnyOrigin()
      .AllowAnyMethod()
      .AllowAnyHeader();
      });
      });
      var app = builder.Build();
      app.UseCors();
      app.UseRouting();
      app.MapMcpServer();
      app.Run();
    }
  }
}

ASP.NET Core 實現方案清晰展示了MCP服務器與Web應用程序的整合邏輯：WithHttpServerTransport() 方法為 MCP 服務器配置基于 HTTP 協議的通信傳輸方式，奠定服務器與外部交互的網絡通信基礎；MapMcpServer() 方法將MCP服務器運行所需的通信端點注冊至 ASP.NET Core 路由系統，實現HTTP請求與MCP服務的自動關聯。

CORS（跨域資源共享）配置是關鍵支撐，允許基于網絡的AI應用程序與MCP服務器建立跨域連接，從而兼容瀏覽器端、Web 服務端等多種客戶端實現。該配置是構建運行于網絡瀏覽器及各類網絡系統中AI代理的核心要素，直接決定了Web場景下MCP服務器的可用性。

圖3：C# SDK組件架構圖，展示了包與其依賴項之間的關系

安全考量與最佳實踐

安全架構與信任模型

MCP協議設計圍繞AI系統訪問外部數據源、執行代碼所帶來的安全風險展開，其安全模型的核心是用戶同意與控制，確保用戶對數據共享及操作執行擁有絕對掌控權。

多層級安全架構：通過定義協議層面的職責邊界，明確客戶端與服務器的安全職責，對敏感操作要求明確授權；客戶端-服務器架構在AI應用與外部資源間構建天然屏障，阻止對安全控制的未授權直接訪問。
用戶授權機制：所有工具調用均需用戶授權后方可執行，協議定義了客戶端在執行前向用戶展示工具描述、參數信息的標準化方式，使用戶可提前知曉操作后果，保持對AI代理活動的人工監督。
數據隱私保護：主機在向服務器傳輸用戶數據前，必須獲得用戶直接許可；協議提供數據傳輸管理工具，助力企業在滿足審計要求的同時，嚴格管控敏感數據，適配企業級安全規范。

認證與授權模式

C# SDK支持開發人員為MCP系統構建靈活的認證與授權體系，可根據安全需求適配從基礎API密鑰認證到企業級復雜身份管理系統（如JWT令牌、OAuth 2.0、Azure Active Directory）等多種方案。

對于基于HTTP的MCP服務器，SDK深度集成ASP.NET Core的身份認證與授權功能，直接復用框架的標準化認證方案。以下為基于HTTP的MCP服務器身份認證配置示例：

public void ConfigureServices(IServiceCollection services)
{
  services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(options =>
  {
    options.TokenValidationParameters = new TokenValidationParameters
    {
      ValidateIssuer = true,
      ValidateAudience = true,
      ValidateLifetime = true,
      ValidateIssuerSigningKey = true,
      ValidIssuer = Configuration["Jwt:Issuer"],
      ValidAudience = Configuration["Jwt:Audience"],
      IssuerSigningKey = new SymmetricSecurityKey(
      Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
    };
  });
  services.AddAuthorization(options =>
  {
    options.AddPolicy("MCPAccess", policy =>
    policy.RequireAuthenticatedUser()
    .RequireClaim("scope", "mcp:read", "mcp:write"));
  });
  services.AddMcpServer()
  .WithHttpServerTransport()
  .WithToolsFromAssembly();
}

該配置方案展示了如何借助標準.NET認證模式為MCP服務器配置權限控制，確保服務器功能僅對授權客戶端開放。其中，基于策略的授權系統支持管理員為用戶配置精細化權限，可精準管控用戶對特定工具及資源的訪問范圍。

基于stdio的MCP服務器的認證過程通過操作系統安全機制在進程級別實現。SDK提供多維度配置選項，支持通過環境變量、命令行參數及配置文件完成客戶端認證，進程級隔離特性在本地開發環境及同類安全場景中適配性優異。

輸入驗證與清理機制

MCP服務器需處理用戶輸入數據并執行外部命令，因此必須具備高強度輸入驗證能力。C# SDK內置多重安全防護功能，為全面輸入驗證提供技術支撐。

其中，基于屬性的工具定義系統集成標準.NET驗證屬性，可直接用于工具參數驗證。以下示例展示如何為MCP工具配置完整的輸入驗證邏輯：

[McpServerToolType]
public static class SecureTools
{
  [McpServerTool, Description("Processes user data with comprehensive
  validation")]
  public static async Task<string> ProcessUserData(
  [Description("User email address")]
  [EmailAddress]
  [Required]
  string email,
  [Description("User age")]
  [Range(0, 150)]
  int age,
  [Description("User input text")]
  [StringLength(1000, MinimumLength = 1)]
  [RegularExpression(@"^[a-zA-Z0-9\s\.,!?-]*$")]
  string inputText)
  {
    // Additional custom validation logic
    if (ContainsSuspiciousContent(inputText))
    {
      throw new ArgumentException("Input contains potentially harmful
      content");
    }
    // Process validated input
    return await ProcessValidatedInput(email, age, inputText);
  }
  private static bool ContainsSuspiciousContent(string input)
  {
    var suspiciousPatterns = new[]
    {
      @"<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>",
      @"javascript:",
      @"vbscript:",
      @"on\w+\s*="
    };
    return suspiciousPatterns.Any(pattern =>
    Regex.IsMatch(input, pattern, RegexOptions.IgnoreCase));
  }
}

該示例呈現了多維度驗證方案，以標準.NET驗證屬性為基礎，逐步拓展至針對危險內容的自定義驗證檢查。這套完整的安全機制確保MCP工具可安全接收用戶輸入，同時避免因注入攻擊或其他安全威脅導致系統漏洞暴露，為工具的輸入安全構建全流程防護屏障。

錯誤處理與日志記錄

完善的錯誤處理與日志記錄系統，是保障系統安全及生產環境問題診斷的核心支撐。C# SDK通過對接.NET內置日志框架，提供了全面的可觀測性能力。

該SDK通過一種將安全措施與用戶友好的錯誤提示相結合的方式來處理錯誤，這種做法能夠防止攻擊者獲取敏感信息。以下為安全錯誤處理模式的示例：

[McpServerToolType]
public static class SecureErrorHandling
{
  private static readonly ILogger _logger = LoggerFactory.Create(builder =>
  builder.AddConsole()).CreateLogger<SecureErrorHandling>();
  [McpServerTool, Description("Demonstrates secure error handling")]
  public static async Task<string> SecureOperation(
  [Description("Operation parameter")] string parameter)
   {
    try
    {
      // Log the operation attempt (without sensitive data)
      _logger.LogInformation("Executing secure operation with parameter
      length: {Length}",
      parameter?.Length ?? 0);
      // Perform the operation
      var result = await PerformSensitiveOperation(parameter);
      _logger.LogInformation("Secure operation completed successfully");
      return result;
    }
    catch (ArgumentException ex)
    {
      // Log validation errors with details for debugging
      _logger.LogWarning("Validation error in secure operation:
      {Message}", ex.Message);
      throw new McpException("Invalid parameter provided");
    }
    catch (UnauthorizedAccessException ex)
    {
      // Log security violations without exposing details
      _logger.LogError("Unauthorized access attempt in secure
      operation");
      throw new McpException("Access denied");
    }
    catch (Exception ex)
    {
      // Log unexpected errors with full details for debugging
      _logger.LogError(ex, "Unexpected error in secure operation");
      throw new McpException("An error occurred while processing the
      request");
    }
  }
}

這種錯誤處理方案實現了雙重核心目標：可捕獲充足的錯誤信息，為問題定位提供完整依據；錯誤消息不會泄露敏感數據，避免給攻擊者可乘之機。同時，結構化日志記錄機制支持對生產環境進行高效監控與實時告警，為系統穩定性提供可視化運維支撐。

性能優化與可擴展性

連接管理與資源優化

高效的連接管理系統是實現MCP-based AI代理可擴展性的核心前提。C# SDK提供多維度工具，支持針對不同部署環境優化資源利用率與連接管理策略。

該SDK采用先進的進程生命周期管理技術，在降低資源占用的同時，確保系統響應速度不受影響；通過連接池機制，實現不同邏輯連接共享傳輸資源，大幅降低進程創建與管理的成本。

基于HTTP的MCP 服務器深度融合了ASP.NET Core成熟的可擴展性特性（包括連接池、請求管道、高效內存管理等），使MCP服務器能夠承載高吞吐量業務，同時保障系統可靠性與性能穩定。

下述示例展示了如何利用連接管理來實現最佳性能：

public void ConfigureServices(IServiceCollection services)
{
  // Configure HTTP client with optimized settings
  services.AddHttpClient<IExternalService, ExternalService>(client =>
  {
    client.Timeout = TimeSpan.FromSeconds(30);
    client.DefaultRequestHeaders.Add("User-Agent", "MCP-Server/1.0");
  })
  .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
  {
    MaxConnectionsPerServer = 10,
    PooledConnectionLifetime = TimeSpan.FromMinutes(5)
  });
  // Configure MCP server with performance optimizations
  services.AddMcpServer(options =>
  {
    options.MaxConcurrentConnections = 100;
    options.ConnectionTimeout = TimeSpan.FromMinutes(10);
    options.EnableConnectionPooling = true;
  })
  .WithHttpServerTransport()
  .WithToolsFromAssembly();
}

緩存與數據管理策略

基于MCP的AI代理在執行高資源消耗決策（如復雜計算、數據庫檢索類任務）時，高效緩存策略可顯著提升運行性能。C# SDK支持開發人員將應用與多類緩存系統集成，覆蓋從基礎內存緩存到分布式緩存的全場景需求。

下述示例將展示如何借助緩存增強MCP工具功能：

[McpServerToolType]
public static class CachedTools
{
  private static readonly IMemoryCache _cache = new MemoryCache(new
  MemoryCacheOptions
  {
  	SizeLimit = 1000
  });
  [McpServerTool, Description("Gets cached weather data")]
  public static async Task<string> GetCachedWeather(
  IWeatherService weatherService,
  [Description("Location to get weather for")] string location)
  {
    var cacheKey = $"weather:{location.ToLowerInvariant()}";
    if (_cache.TryGetValue(cacheKey, out string cachedResult))
    {
    	return cachedResult;
    }
    var weather = await weatherService.GetWeatherAsync(location);
    var result = JsonSerializer.Serialize(weather);
    var cacheOptions = new MemoryCacheEntryOptions
    {
      AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
      Size = 1
    };
    _cache.Set(cacheKey, result, cacheOptions);
    return result;
  }
}

這種緩存系統通過優化高頻信息獲取路徑，確保用戶便捷獲取常用數據；同時通過時效性管控機制避免推送過期內容，實現性能穩定性與數據時效性的平衡。

測試與質量保證

MCP 組件的單元測試策略

基于MCP的AI代理測試需采用針對性方法，既要適配系統的分布式特性，也要兼顧AI交互的復雜性。C# SDK憑借依賴注入與接口化抽象設計，為組件的完整測試提供了技術支撐，支持開發人員構建全面的測試用例。

下述示例將展示如何為MCP工具編寫高效單元測試：

[TestClass]
public class MCPToolTests
{
  private Mock<IWeatherService> _mockWeatherService;
  private Mock<ILogger<WeatherTools>> _mockLogger;
  [TestInitialize]
  public void Setup()
  {
    _mockWeatherService = new Mock<IWeatherService>();
    _mockLogger = new Mock<ILogger<WeatherTools>>();
  }
  [TestMethod]
  public async Task GetWeather_ValidLocation_ReturnsWeatherData()
  {
    // Arrange
    var expectedWeather = new WeatherData
    {
    Location = "New York",
    Temperature = 22.5,
    Description = "Sunny"
    };
    _mockWeatherService
    .Setup(s => s.GetWeatherAsync("New York"))
    .ReturnsAsync(expectedWeather);
    // Act
    var result = await WeatherTools.GetWeather(_mockWeatherService.Object,
    "New York");
    // Assert
    Assert.IsNotNull(result);
    var weatherData = JsonSerializer.Deserialize<WeatherData>(result);
    Assert.AreEqual("New York", weatherData.Location);
    Assert.AreEqual(22.5, weatherData.Temperature);
  }
  [TestMethod]
  public async Task GetWeather_ServiceThrowsException_HandlesGracefully()
  {
    // Arrange
    _mockWeatherService
    .Setup(s => s.GetWeatherAsync(It.IsAny<string>()))
    .ThrowsAsync(new HttpRequestException("Service unavailable"));
    // Act & Assert
    await Assert.ThrowsExceptionAsync<HttpRequestException>(
    () => WeatherTools.GetWeather(_mockWeatherService.Object,
    "Invalid"));
  }
}

集成測試與端到端驗證

MCP系統的集成測試需對存在外部依賴關系的多系統組件開展協同驗證。C# SDK內置專屬測試工具，為開發人員構建全面的集成測試場景提供支撐，可有效覆蓋組件間交互、外部依賴調用等復雜測試需求。

[TestClass]
public class MCPIntegrationTests
{
  private TestServer _testServer;
  private HttpClient _httpClient;
  private IMcpClient _mcpClient;
  [TestInitialize]
  public async Task Setup()
  {
    var builder = WebApplication.CreateBuilder();
    builder.Services.AddMcpServer()
    .WithHttpServerTransport()
    .WithToolsFromAssembly();
    var app = builder.Build();
    app.MapMcpServer();
    _testServer = new TestServer(app);
    _httpClient = _testServer.CreateClient();
    var transport = new HttpClientTransport(_httpClient,
    "http://localhost");
    _mcpClient = await McpClientFactory.CreateAsync(transport);
  }
  [TestMethod]
  public async Task EndToEndToolExecution_Success()
  {
    // Act
    var tools = await _mcpClient.ListToolsAsync();
    var echoTool = tools.FirstOrDefault(t => t.Name == "Echo");
    Assert.IsNotNull(echoTool);
    var result = await _mcpClient.CallToolAsync("Echo",
    new Dictionary<string, object?> { ["message"] = "Test" });
    // Assert
    Assert.IsNotNull(result);
    var textContent = result.Content.FirstOrDefault(c => c.Type == "text");
    Assert.IsNotNull(textContent);
    Assert.AreEqual("Echo: Test", textContent.Text);
  }
}

部署與生產環境考量

現代部署實踐中，基于MCP的AI代理常采用容器化技術實現跨環境一致性部署，C# SDK依托內置的.NET容器功能，天然支持容器化部署。盡管當前仍有企業采用傳統非容器化部署（如本地部署、云原生部署等），但本文將重點聚焦于應用更廣泛的容器化部署方案。

基于容器的部署策略

容器化部署是當前MCP AI代理的主流現代部署方式，其核心優勢在于保障開發、測試、生產環境的一致性，簡化部署流程與運維成本。C# SDK通過原生支持.NET容器特性，進一步降低了容器化部署的實施難度。

以下為用于構建MCP服務器容器的Dockerfile示例：

Dockerfile

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MCPServer.csproj", "."]
RUN dotnet restore "MCPServer.csproj"
COPY . .
WORKDIR "/src"
RUN dotnet build "MCPServer.csproj" -c Release -o /app/build
FROM build AS publish
RUN dotnet publish "MCPServer.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MCPServer.dll"]

監控與可觀測性

部署于生產環境的MCP系統，需配備完善的監控體系與可觀測性工具，這是保障系統穩定運行、實現高效故障排查的核心前提。C# SDK與.NET原生可觀測性功能深度集成，能夠實時輸出系統行為的詳細數據，為運維監控提供全面支撐。

public void ConfigureServices(IServiceCollection services)
{
  // Configure telemetry
  services.AddApplicationInsightsTelemetry();
  // Configure health checks
  services.AddHealthChecks()
  .AddCheck<MCPServerHealthCheck>("mcp-server")
  .AddCheck<ExternalServiceHealthCheck>("external-services");
  // Configure metrics
  services.AddSingleton<IMeterFactory, MeterFactory>();
  services.AddMcpServer()
  .WithHttpServerTransport()
  .WithToolsFromAssembly();
  }
  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  {
  app.UseHealthChecks("/health");
  app.UseMetrics();
  app.MapMcpServer();
}

在VS Code中結合GitHub Copilot與MCP構建AI代理

設置與配置流程

開發人員需先完成GitHub Copilot擴展的安裝與訂閱激活，方可在Visual Studio Code（以下簡稱VS Code）中搭建融合GitHub Copilot與模型上下文協議（MCP）的AI代理。具體流程為：在完成擴展安裝與訂閱驗證后，通過VS Code的系統設置配置MCP服務器連接；集成的核心步驟是在工作區的 .vscode 文件夾或用戶設置目錄下，創建或修改 mcp.json 配置文件，以此定義包含傳輸配置的MCP服務器參數。

步驟1：必備條件

在VS Code中安裝GitHub Copilot擴展程序。
擁有有效的GitHub Copilot訂閱服務。
部署并運行可用的MCP服務器（上述提供了C#示例）。

步驟2：MCP 服務器配置

在工作區的 .vscode 文件夾內，創建名為 mcp.json 的配置文件，并按以下指定結構完成參數設置：

JSON

{
  "servers": {
    "MyMCPServer": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "path/to/your/MCPServer.csproj"]
    }
  }
}

步驟3：激活代理模式

啟動VS Code并打開已完成配置的目標工作區；
打開GitHub Copilot聊天面板：Windows/Linux系統按 Ctrl+Shift+I ，Mac系統按 Cmd+Shift+I ；
開啟代理模式：在聊天界面中找到代理圖標，將“代理模式”切換為啟用狀態；
完成激活：此時AI代理已準備就緒，可調用配置的MCP工具開展業務操作。

步驟4：使用人工智能代理

代理模式啟用后，GitHub Copilot可訪問已配置MCP服務器提供的工具、資源及提示模板，支持以下操作場景：

提出需結合數據分析或調用外部工具的復雜問題；
發起特定任務請求，例如“分析此文本文件并生成報告”；
執行多步驟串聯操作，如數據獲取、數據處理、可視化圖表生成等。

步驟5：工具執行流程

在AI代理調用工具的過程中，VS Code將按以下流程自動執行操作：

1. 工具信息展示：清晰呈現待調用工具的名稱、功能描述及所需參數；

2. 用戶授權請求：彈出對話框，向用戶發起工具執行許可請求；

3. 已授權工具執行：根據用戶確認的許可，使用指定參數運行工具；

4. 結果整合反饋：將工具輸出結果整合至AI響應內容中，同步展示給用戶。

遠程MCP服務器訪問配置

以下示例為遠程部署MCP服務器的訪問方案，適用于跨環境使用需求。

重要提示：本示例僅用于教學演示。在生產環境中，必須采用符合安全規范的方式管理API密鑰、令牌及各類認證信息，嚴防數據泄露與未授權訪問。

基于HTTP的遠程MCP服務器

基本的HTTP配置

JSON

{
   "servers": {
       "remote-api-server": {
         "type": "http",
         "url": "https://api.example.com/mcp",
         "headers": {
         "User-Agent": "VSCode-MCP-Client/1.0",
         "Accept": "application/json"
       }
     }
   }
}

配置API密鑰認證的HTTP協議

JSON

{
    "servers": {
        "authenticated-server": {
            "type": "http",
            "url": "https://secure-api.company.com/mcp",
            "headers": {
                "Authorization": "your-api-key-here",
                "X-API-Version": "2024-01-01",
                "Content-Type": "application/json"
            },
            "timeout": 30000
        }
    }
}

配置自定義標頭和環境變量的HTTP協議

JSON

{
    "servers": {
        "enterprise-server": {
            "type": "http",
            "url": "https://internal.company.com/mcp-gateway",
            "headers": {
                "Authorization": "Bearer ${MCP_API_TOKEN}",
                "X-Client-ID": "${MCP_CLIENT_ID}",
                "X-Environment": "production"
            },
            "env": {
                "MCP_API_TOKEN": "your-token-from-env",
                "MCP_CLIENT_ID": "your-client-id"
            }
        }
    }
}

服務器推送事件（SSE）配置

基本的SSE配置

JSON

{
    "servers": {
        "realtime-data-server": {
            "type": "sse",
            "url": "https://streaming.example.com/mcp/events",
            "headers": {
                "Authorization": "your-streaming-token",
                "Cache-Control": "no-cache"
            },
            "reconnect": true,
            "reconnectInterval": 5000
        }
    }
}

帶有自定義配置的SSE

JSON

{
    "servers": {
        "live-analytics": {
            "type": "sse",
            "url": "https://analytics.company.com/mcp/stream",
            "headers": {
                "Authorization": "Bearer ${ANALYTICS_TOKEN}",
                "X-Stream-Type": "mcp-events"
            },
            "options": {
                "withCredentials": true,
                "heartbeatTimeout": 30000,
                "maxRetries": 3
            }
        }
    }
}

Azure云托管的MCP服務器

JSON

{
    "servers": {
        "azure-mcp-service": {
            "type": "http",
            "url": "https://your-app.azurewebsites.net/mcp",
            "headers": {
                "Authorization": "Bearer ${AZURE_MCP_TOKEN}",
                "X-Azure-Region": "eastus",
                "X-Subscription-ID": "${AZURE_SUBSCRIPTION_ID}"
            },
            "env": {
                "AZURE_MCP_TOKEN": "your-azure-token",
                "AZURE_SUBSCRIPTION_ID": "your-subscription-id"
            }
        }
    }
}

未來發展趨勢與新出現的模式

AI代理架構的演進

模型上下文協議（MCP）雖已確立AI代理的標準化架構，但該領域仍處于快速發展階段。未來AI代理的核心發展方向是強化復雜場景適配能力，能夠在多步驟工作流中統籌管理各類工具與數據源，實現更高效的任務協同。

C# SDK以靈活性設計適配未來需求變化：協議內置的能力協商機制具備良好兼容性，支持無縫新增功能與特性，確保MCP實現可隨協議迭代持續運行，無需中斷服務，從而快速響應新場景、新需求。

與大型語言模型（LLM）生態的深度整合

MCP通過持續迭代功能，保持與各類LLM生態的緊密集成。C# SDK與 Microsoft.Extensions.AI 深度對接，依托統一的接口與行為模式，為適配不同LLM提供商奠定技術基礎。

未來發展將聚焦三大方向：

強化多模態交互支持；
優化擴展對話中的上下文管理能力；
提供更先進的工具組合策略。

SDK的模塊化結構與依賴注入特性，為新功能的快速落地提供了穩定支撐，確保技術迭代的高效性。

結語

模型上下文協議（MCP）是AI代理發展的重要里程碑，為AI系統與外部數據、工具的交互提供了標準化框架。本文研究表明，開發人員可依托C#語言及.NET生態，通過MCP的架構落地、實踐應用，構建安全可擴展的復雜AI代理。

該研究全面剖析了MCP的設計原則、架構邏輯，結合官方C# SDK的實施指南與實際應用示例，形成完整的技術落地體系。安全指南和最佳實踐為生產環境部署MCP系統提供關鍵指導，滿足高可靠性、高安全性的核心需求。

C# SDK與.NET生態的深度集成，提升了企業開發效率。依賴注入、完備測試功能及現有.NET基礎設施的復用，助力開發人員構建符合企業開發標準的人工智能代理。

隨著AI技術迭代及代理系統復雜度提升，MCP的標準化框架將成為開發安全、可維護、可協同AI系統的核心支撐，在AI代理生態中的重要性將持續凸顯。

本文提供的示例與模式，為開發人員構建生產級AI代理奠定基礎——這類代理能夠連接大型語言模型（LLM）與真實世界數據源，兼具功能完整性與能力擴展性，同時保障安全性、可靠性與可維護性。

MCP與C# SDK仍在不斷演進，將為開發人員提供更先進的工具以構建下一代AI代理。MCP的標準化方法，結合.NET生態的強大開發能力，將共同打造高效、穩定的AI代理開發平臺，推動AI技術在實際場景中的深度應用。

原文標題：Creating AI Agents Using the Model Context Protocol: A Comprehensive Guide to Implementation with C#，作者：Nilesh Bhandarwar

責任編輯：火鳳凰來源： 51CTO

MCP C#人工智能代理 AI