ASP.NET Core WebApi 集成 MCP 协议完全指南

前言

Model Context Protocol (MCP) 是一个标准化协议，让 AI 客户端（如 Claude、ChatGPT 等）能够通过统一的接口调用你的 API。本文将详细介绍如何在 ASP.NET Core WebApi 项目中集成 MCP 支持，实现 AI 与你的服务无缝对接。
什么是 MCP？

MCP（Model Context Protocol）是一个开放协议，旨在标准化 AI 应用与外部工具、数据源之间的通信方式。通过 MCP，你的 API 可以：

• 被 AI 助手自动发现和调用
  
• 提供标准化的工具描述和参数定义
  
• 支持多种传输模式（HTTP、Stdio）
  
• 实现安全的认证和授权
  

核心特性

本项目实现了以下功能：

• ✅ 使用官方 ModelContextProtocol.AspNetCore SDK
  
• ✅ 通过 [McpServerTool] 特性快速定义工具
  
• ✅ 自动参数绑定和 JSON Schema 生成
  
• ✅ 支持 HTTP 和 Stdio 双传输模式
  
• ✅ 基于 Token 的认证和授权
  
• ✅ 与现有 WebApi 完美共存
  

快速开始

第一步：安装 NuGet 包

1. dotnet add package ModelContextProtocol.AspNetCore --version 0.4.0-preview.3

复制代码

第二步：配置 MCP 服务

在 Program.cs 中添加 MCP 配置：

1. using ModelContextProtocol.Server;
3. var builder = WebApplication.CreateBuilder(args);
5. builder.Services.AddControllers();
7. // 添加 MCP 服务器（支持 HTTP 和 Stdio 双模式）
8. builder.Services
9.     .AddMcpServer(options =>
10.     {
11.         options.ServerInfo = new ModelContextProtocol.Protocol.Implementation
12.         {
13.             Name = "Weather API",
14.             Version = "1.0.0"
15.         };
16.     })
17.     .WithHttpTransport()           // HTTP 模式：用于 Web 客户端
18.     .WithStdioServerTransport()    // Stdio 模式：用于 Kiro IDE 等本地工具
19.     .WithToolsFromAssembly();
21. var app = builder.Build();
23. // 添加认证中间件（可选）
24. app.UseMiddleware<McpAuthenticationMiddleware>();
26. app.UseAuthorization();
27. app.MapControllers();
29. // 映射 MCP 端点
30. app.MapMcp("/mcp");
32. app.Run();

复制代码

第三步：定义 MCP 工具

创建 Tools/WeatherTools.cs：

1. using System.ComponentModel;
2. using ModelContextProtocol.Server;
4. [McpServerToolType]
5. public static class WeatherTools
6. {
7.     [McpServerTool]
8.     [Description("Get weather forecast for the next 5 days")]
9.     public static IEnumerable<WeatherForecast> GetWeatherForecast()
10.     {
11.         var rng = new Random();
12.         return Enumerable.Range(1, 5).Select(index => new WeatherForecast
13.         {
14.             Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
15.             TemperatureC = rng.Next(-20, 55),
16.             Summary = Summaries[rng.Next(Summaries.Length)]
17.         }).ToArray();
18.     }
20.     [McpServerTool]
21.     [Description("Get current weather for a specific city")]
22.     public static WeatherForecast GetWeatherByCity(
23.         [Description("The name of the city")] string city)
24.     {
25.         var rng = new Random();
26.         return new WeatherForecast
27.         {
28.             Date = DateOnly.FromDateTime(DateTime.Now),
29.             TemperatureC = rng.Next(-20, 55),
30.             Summary = $"Weather in {city}: {Summaries[rng.Next(Summaries.Length)]}"
31.         };
32.     }
34.     private static readonly string[] Summaries = new[]
35.     {
36.         "Freezing", "Bracing", "Chilly", "Cool", "Mild",
37.         "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
38.     };
39. }

复制代码

第四步：配置认证（可选）

在 appsettings.json 中配置：

1. {
2.   "McpAuth": {
3.     "Enabled": true,
4.     "ValidTokens": ["your-secret-token-here"]
5.   }
6. }

复制代码

开发环境可以禁用认证（appsettings.Development.json）：

1. {
2.   "McpAuth": {
3.     "Enabled": false
4.   }
5. }

复制代码

第五步：运行和测试

1. dotnet run

复制代码

应用启动后，可以访问：

• Swagger UI: http://localhost:5000/swagger
  
• WebApi: http://localhost:5000/weatherforecast
  
• MCP 端点: http://localhost:5000/mcp
  

传输模式详解

HTTP 模式

适用于 Web 应用、Claude Desktop、远程访问等场景。
测试示例：

1. # 列出所有工具
2. curl -X POST http://localhost:5000/mcp \
3.   -H "Content-Type: application/json" \
4.   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
6. # 调用工具
7. curl -X POST http://localhost:5000/mcp \
8.   -H "Authorization: Bearer your-secret-token-here" \
9.   -H "Content-Type: application/json" \
10.   -d '{
11.     "jsonrpc":"2.0",
12.     "id":2,
13.     "method":"tools/call",
14.     "params":{
15.       "name":"GetWeatherForecast",
16.       "arguments":{}
17.     }
18.   }'

复制代码

Claude Desktop 配置：
编辑配置文件（Windows: %APPDATA%\Claude\claude_desktop_config.json）：

1. {
2.   "mcpServers": {
3.     "weather-api": {
4.       "url": "http://localhost:5000/mcp",
5.       "headers": {
6.         "Authorization": "Bearer your-secret-token-here"
7.       }
8.     }
9.   }
10. }

复制代码

Stdio 模式

适用于 Kiro IDE、本地命令行工具等场景，无需网络端口。
Kiro IDE 配置：
编辑 .kiro/settings/mcp.json：

1. {
2.   "mcpServers": {
3.     "weather-api": {
4.       "command": "dotnet",
5.       "args": ["run", "--project", "path/to/NetCoreApiMcpDemo.csproj"],
6.       "env": {
7.         "ASPNETCORE_ENVIRONMENT": "Development"
8.       }
9.     }
10.   }
11. }

复制代码

模式对比

特性HTTP 模式Stdio 模式传输方式HTTP POST标准输入/输出适用场景Web 应用、远程访问本地工具、IDE 集成认证HTTP Header环境变量/配置网络需要网络端口无需网络性能网络开销进程间通信，更快认证和授权

实现认证中间件

创建 Middleware/McpAuthenticationMiddleware.cs：

1. public class McpAuthenticationMiddleware
2. {
3.     private readonly RequestDelegate _next;
4.     private readonly IConfiguration _configuration;
5.     private readonly ILogger<McpAuthenticationMiddleware> _logger;
7.     public McpAuthenticationMiddleware(
8.         RequestDelegate next,
9.         IConfiguration configuration,
10.         ILogger<McpAuthenticationMiddleware> logger)
11.     {
12.         _next = next;
13.         _configuration = configuration;
14.         _logger = logger;
15.     }
17.     public async Task InvokeAsync(HttpContext context)
18.     {
19.         // 只对 MCP 端点进行认证
20.         if (!context.Request.Path.StartsWithSegments("/mcp"))
21.         {
22.             await _next(context);
23.             return;
24.         }
26.         // 检查是否启用认证
27.         var authEnabled = _configuration.GetValue<bool>("McpAuth:Enabled");
28.         if (!authEnabled)
29.         {
30.             await _next(context);
31.             return;
32.         }
34.         // 验证 Token
35.         var authHeader = context.Request.Headers["Authorization"].FirstOrDefault();
36.         if (string.IsNullOrEmpty(authHeader) || !authHeader.StartsWith("Bearer "))
37.         {
38.             context.Response.StatusCode = 401;
39.             await context.Response.WriteAsJsonAsync(new { error = "Unauthorized" });
40.             return;
41.         }
43.         var token = authHeader.Substring("Bearer ".Length).Trim();
44.         var validTokens = _configuration.GetSection("McpAuth:ValidTokens").Get<string[]>();
46.         if (validTokens == null || !validTokens.Contains(token))
47.         {
48.             context.Response.StatusCode = 401;
49.             await context.Response.WriteAsJsonAsync(new { error = "Invalid token" });
50.             return;
51.         }
53.         await _next(context);
54.     }
55. }

复制代码

安全最佳实践

• 使用强 Token：至少 32 字符的随机字符串
  
• 定期轮换：定期更换 Token
  
• 使用 HTTPS：生产环境必须使用 HTTPS
  
• 环境隔离：开发和生产使用不同的 Token
  
• 日志安全：不要在日志中记录完整 Token
  

客户端集成示例

C# 客户端

1. using ModelContextProtocol;
2. using ModelContextProtocol.Client;
4. var transport = new HttpClientTransport(new HttpClientTransportOptions
5. {
6.     BaseUrl = new Uri("http://localhost:5000/mcp"),
7.     Headers = new Dictionary<string, string>
8.     {
9.         ["Authorization"] = "Bearer your-secret-token-here"
10.     }
11. });
13. var client = await McpClient.CreateAsync(transport);
15. await client.InitializeAsync(new InitializeParams
16. {
17.     ProtocolVersion = "2025-06-18",
18.     ClientInfo = new Implementation
19.     {
20.         Name = "MyApp",
21.         Version = "1.0.0"
22.     }
23. });
25. // 列出工具
26. var tools = await client.ListToolsAsync();
28. // 调用工具
29. var result = await client.CallToolAsync(
30.     "GetWeatherForecast",
31.     new Dictionary<string, object?>()
32. );

复制代码

JavaScript/Vue 客户端

1. [/code][size=5]MCP Tools 最佳实践[/size]
3. 让 AI 更准确地使用你的工具是成功的关键。以下是经过实践验证的最佳实践。
4. [size=4]核心原则[/size]
6. AI 通过以下信息决定是否使用你的工具：
7. [list=1]
8. [*][b]工具名称[/b] - 清晰、描述性
9. [*][b]Description[/b] - 详细的功能说明
10. [*][b]参数描述[/b] - 明确的参数用途
11. [*][b]使用场景[/b] - 何时应该使用这个工具
12. [/list][size=4]1. 使用清晰的命名[/size]
14. [code]// ❌ 不好 - 名称模糊
15. [McpServerTool]
16. public static string Get() { }
18. // ✅ 好 - 动词开头，描述清晰
19. [McpServerTool]
20. public static string GetWeatherForecast() { }
22. // ✅ 更好 - 包含具体信息
23. [McpServerTool]
24. public static string GetWeatherForecastForNextDays() { }

复制代码

命名建议：

• 使用动词开头：Get, Search, Calculate, Compare, Analyze
  
• 包含操作对象：Weather, Temperature, Forecast
  
• 避免缩写和简称
  
• 使用 PascalCase
  

2. 编写详细的 Description（最重要！）

这是最关键的部分！AI 主要通过 Description 判断是否使用工具。

1. // ❌ 不好 - 太简短
2. [Description("Get weather")]
4. // ⚠️ 一般 - 有基本信息但不够
5. [Description("Get weather forecast for the next 5 days")]
7. // ✅ 好 - 包含详细信息和使用场景
8. [Description(@"Get detailed weather forecast for the next several days including temperature, weather conditions, and trends.
10. Use this tool when users ask about:
11. - Future weather (tomorrow, next week, upcoming days)
12. - Weather predictions or forecasts
13. - Planning activities based on weather
14. - Temperature trends
16. Examples of user queries:
17. - 'What's the weather forecast for the next 5 days?'
18. - 'Will it rain this week?'
19. - 'What's the temperature trend?'")]

复制代码

Description 应该包含：

• 功能说明 - 工具做什么
  
• 使用场景 - 何时使用（"Use this tool when..."）
  
• 示例查询 - 用户可能的提问方式
  
• 支持的功能 - 特殊能力或限制
  

3. 详细的参数描述

1. [McpServerTool]
2. public static string GetWeatherByCity(
3.     // ❌ 不好
4.     [Description("city")] string city,
6.     // ✅ 好
7.     [Description("The name of the city in English or Chinese (e.g., 'Beijing', '北京', 'Shanghai', 'New York')")]
8.     string city,
10.     // ✅ 更好 - 包含默认值说明
11.     [Description("Number of days to forecast (1-7 days). Default is 5 days if not specified.")]
12.     int days = 5
13. )

复制代码

参数描述应该包含：

• 参数的用途
  
• 支持的格式或值范围
  
• 示例值
  
• 默认值（如果有）
  

4. 返回格式化、易读的结果

[code]// ❌ 不好 - 返回原始对象public static WeatherForecast GetWeather(string city){    return new WeatherForecast { ... };}// ✅ 好 - 返回格式化的文本public static string GetWeather(string city){    var weather = GetWeatherData(city);    return $@"
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

过来提前占个楼