- 教程
- 文档
- 人工智能
【免费下载链接】mcp-for-beginners
This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.
AI 智能体（Agent）的价值不只在于"生成聪明的回答"，更在于"真正采取行动"。本指南基于 mcp-for-beginners 课程的第 7 课，完整演示如何借助AI Toolkit for Visual Studio Code扩展，把计算器 MCP 服务器接入 Agent（Prompt）Builder，让 Agent 通过一句自然语言提示就能完成加、减、乘、除运算。学完本文，你将掌握在 VSCode 中创建 Agent、定义系统提示、用模板搭建 Python MCP 服务器、将二者连通并通过自然语言触发工具调用的全流程，并了解如何为服务器扩展新工具。
概览：为什么需要 MCP 与 AI Toolkit
当你在构建 AI Agent 时，除了让它生成回答，还要赋予它操作外部世界的能力。Model Context Protocol（MCP）正是为此而生——它用一种一致的方式，让 Agent 访问外部工具与服务。你可以把它理解为"把 Agent 插进一个它真正能用的工具箱"。
想象一下：你把 Agent 连上自己的计算器 MCP 服务器，它就能仅凭一句"47 乘以 89 等于多少？"完成数学运算，无需硬编码逻辑，也无需自建 API。
本课的核心流程如下：
- 创建 Agent 并定义其系统提示（system prompt）；
- 创建带计算工具（加、减、乘、除）的 MCP 服务器；
- 用 Agent（Prompt）Builder 连接该 MCP 服务器；
- 通过自然语言测试 Agent 的工具调用。
AI Toolkit 是 Visual Studio Code 上的一个功能强大的扩展，能显著简化 Agent 的开发：AI 工程师可以方便地构建 AI 应用，并在本地或云端开发、测试生成式 AI 模型，且该扩展支持当今绝大多数主流生成式模型。
[!NOTE] AI Toolkit 目前支持Python和TypeScript的 MCP 模板。
学习目标
完成本课学习后，你将能够：
- 通过 AI Toolkit 消费（consume）MCP 服务器；
- 配置 Agent，使其能发现并使用 MCP 服务器提供的工具；
- 通过自然语言使用 MCP 工具。
前置条件
- Visual Studio Code
- AI Toolkit for Visual Studio Code
[!WARNING]macOS 用户请注意：目前官方正在调查影响 macOS 上依赖安装的问题，因此 macOS 用户暂时无法完成本课练习。一旦修复方案可用，课程说明会同步更新。
练习总览：构建、运行并增强带 MCP 工具的 Agent
在本练习中，你将直接在 Visual Studio Code 中，使用 AI Toolkit 构建、运行并增强一个带 MCP 服务器工具的 AI Agent。整体分为 5 个步骤：-0添加模型、-1创建 Agent、-2生成系统提示、-3创建 MCP 服务器、-4运行 Agent 并验证工具调用。
步骤 -0：把 GPT-4o 模型加入 My Models
本练习使用GPT-4o模型，因此必须在创建 Agent 之前，先把它添加到My Models列表。
- 从Activity Bar（活动栏）打开AI Toolkit扩展。
- 在Catalog区域选择Models打开Model Catalog，它会在新的编辑器标签页中打开。
- 在Model Catalog的搜索框中输入OpenAI GPT-4o。
- 点击+ Add将该模型添加到My Models列表，确保选择的是hosted on GitHub（GitHub 托管）的模型。
- 回到Activity Bar，确认OpenAI GPT-4o已出现在列表中。
步骤 -1：创建 Calculator Agent
Agent（Prompt）Builder允许你创建并定制自己的 AI 驱动 Agent。本步将新建一个 Agent，并为其指定驱动对话的模型。
- 从Activity Bar打开AI Toolkit扩展。
- 在Tools区域选择Agent (Prompt) Builder，它会在新的编辑器标签页中打开。
- 点击+ New Agent按钮，扩展将通过Command Palette启动设置向导。
- 输入名称Calculator Agent并按下Enter。
- 在Agent (Prompt) Builder的Model字段中，选择模型OpenAI GPT-4o (via GitHub)。
步骤 -2：为 Agent 生成系统提示
Agent 骨架搭好后，就该定义它的"人设"与用途了。本步使用Generate system prompt功能，描述 Agent 的预期行为——本例是一个计算器 Agent——让模型替你写出系统提示。
- 在Prompts区域点击Generate system prompt按钮，会打开一个利用 AI 为 Agent 生成系统提示的提示构建器。
- 在Generate a prompt窗口中输入以下内容：
You are a helpful and efficient math assistant. When given a problem involving basic arithmetic, you respond with the correct result. - 点击Generate按钮。右下角会出现通知，确认系统提示正在生成。生成完成后，提示会出现在Agent (Prompt) Builder的System prompt字段中。
- 检查System prompt，如有需要可手动修改。
步骤 -3：创建计算器 MCP 服务器
系统提示决定了 Agent 的行为与回答方式，接下来要为它装备"实际能力"。本步将创建一个计算器 MCP 服务器，提供加、减、乘、除四种工具，让 Agent 能根据自然语言请求实时完成数学运算。
AI Toolkit 自带便于创建 MCP 服务器的模板，本练习使用Python 模板创建计算器服务器。
- 在Agent (Prompt) Builder的Tools区域点击+ MCP Server按钮，扩展会通过Command Palette启动设置向导。
- 选择+ Add Server。
- 选择Create a New MCP Server。
- 选择python-weather作为模板。
- 选择Default folder保存 MCP 服务器模板。
- 输入服务器名称：Calculator。
- 会打开一个新的 Visual Studio Code 窗口，选择Yes, I trust the authors。
- 使用终端（Terminal>New Terminal）创建虚拟环境：
python -m venv .venv - 使用终端激活虚拟环境：
- Windows：
.venv\Scripts\activate - macOS/Linux：
source .venv/bin/activate
- Windows：
- 使用终端安装依赖：
pip install -e .[dev] - 在Activity Bar的Explorer视图中展开src目录，选择server.py在编辑器中打开。
- 用以下代码替换server.py中的内容并保存：
""" Sample MCP Calculator Server implementation in Python. This module demonstrates how to create a simple MCP server with calculator tools that can perform basic arithmetic operations (add, subtract, multiply, divide). """ from mcp.server.fastmcp import FastMCP server = FastMCP("calculator") @server.tool() def add(a: float, b: float) -> float: """Add two numbers together and return the result.""" return a + b @server.tool() def subtract(a: float, b: float) -> float: """Subtract b from a and return the result.""" return a - b @server.tool() def multiply(a: float, b: float) -> float: """Multiply two numbers together and return the result.""" return a * b @server.tool() def divide(a: float, b: float) -> float: """ Divide a by b and return the result. Raises: ValueError: If b is zero """ if b == 0: raise ValueError("Cannot divide by zero") return a / b源码视角：FastMCP 工具注册机制
上面的实现只用了三行关键代码：from mcp.server.fastmcp import FastMCP、server = FastMCP("calculator")与@server.tool()装饰器。这一模式与本仓库中其他 Python 示例一脉相承，例如 01-first-server 的 server.py 中同样以mcp = FastMCP("Demo")创建服务器实例，并用@mcp.tool()注册add、subtract两个工具。从源码结构可以推断，@server.tool()装饰器会把被装饰的函数注册为可供客户端发现和调用的 MCP 工具：函数名成为工具名，类型注解与 docstring 会被推导为工具的输入 Schema 与描述，正是它们让 Agent（模型）能够"读懂"每个工具的用途并正确填入参数。这也解释了为什么除零检查要写在divide内部并抛出ValueError——把业务校验放进工具自身，错误就能以可预期的形式回传给调用方。
此外，仓库中更进阶的示例展示了如何继续扩展这一模型，例如 06-http-streaming 的 server.py 引入了FastMCP与Context，注册了root、event_stream、stream、process_files等工具与资源，说明同一个FastMCP实例可以承载工具、资源和流式端点；而 11-simple-auth 的 server.py 则在 FastMCP 之上叠加了认证逻辑。这些示例可以作为你在 AI Toolkit 模板基础上继续深挖的参考资料。
步骤 -4：运行带计算器 MCP 服务器的 Agent
工具就绪，现在开始使用它们！本步向 Agent 提交提示，验证它是否会调用计算器 MCP 服务器中的正确工具。计算器 MCP 服务器将运行在你的本地开发机上，Agent Builder 充当 MCP 客户端。
- 按
F5开始调试 MCP 服务器。Agent（Prompt）Builder会在新的编辑器标签页中打开，服务器状态显示在终端中。 - 在Agent（Prompt）Builder的User prompt字段中输入以下提示：
I bought 3 items priced at $25 each, and then used a $20 discount. How much did I pay? - 点击Run按钮生成 Agent 的回复。
- 检查 Agent 的输出，模型应得出结论：你支付了55 美元。
- 预期发生的过程如下：
- Agent 选择multiply与subtract工具协助计算；
- 为multiply工具分配相应的
a、b参数值； - 为subtract工具分配相应的
a、b参数值； - 每个工具的回答显示在对应的Tool Response字段中；
- 模型的最终输出显示在最终的Model Response中。
- 提交更多提示进一步测试 Agent。可以点击User prompt字段内部、替换文本以修改现有提示。
- 测试完成后，在终端中按CTRL/CMD+C停止服务器。
从结果面板可以看到，Agent 把自然语言问题"翻译"成了两次结构化的工具调用：先以{"a": 3, "b": 25}调用multiply（3 × 25 = 75），再以{"a": 75, "b": 20}调用subtract（75 − 20 = 55），最后把工具返回的75.0等结果组织成面向用户的回答。这正是 MCP 客户端工作流的缩影——关于客户端如何以编程方式列出工具并调用它们，可参考 02-client 一课的 TypeScript 示例（其中展示了client.listTools()/client.callTool()的调用模式）。
课后作业：为服务器扩展平方根工具
尝试在server.py中添加一个新工具（例如：返回一个数的平方根）。然后提交需要 Agent 使用新工具（或已有工具）的提示，记得重启服务器以加载新添加的工具。
作业参考解法
完整的参考实现位于 07-aitk/solution/README.md。核心思路是在原有四个工具之外，新增一个sqrt工具：
import math @server.tool() def sqrt(a: float) -> float: """ Return the square root of a. Raises: ValueError: If a is negative. """ if a < 0: raise ValueError("Cannot compute the square root of a negative number.") return math.sqrt(a)其工作原理如下：
- 导入
math模块：Python 内置的math模块提供了math.sqrt()等数学函数与常量； - 函数定义：
@server.tool()装饰器把sqrt函数注册为 AI Agent 可访问的工具； - 输入参数：函数接受一个
float类型的参数a； - 错误处理：当
a为负数时抛出ValueError，避免对负数开平方（math.sqrt()不支持）； - 返回值：对非负输入，使用
math.sqrt()返回a的平方根。
添加新工具后，务必重启 MCP 服务器，Agent 才能识别并使用新增功能。可用以下自然语言提示验证：
- "What is the square root of 25?"
- "Calculate the square root of 81."
- "Find the square root of 0."
- "What is the square root of 2.25?"
扩展验证：单元测试思路
如果你想让服务器行为可验证，本仓库的 08-testing 一课 给出了使用pytest对 FastMCP 服务器做单元测试的范例：借助mcp.shared.memory的create_connected_server_and_client_session创建"服务器-客户端"内存会话，再通过client_session.list_tools()等断言工具是否按预期注册。把这一模式套用到计算器服务器上，即可为add、divide、sqrt等工具编写自动化的行为测试。
关键要点
- AI Toolkit 是一个出色的客户端，让你能够使用 MCP 服务器及其工具；
- 你可以不断向 MCP 服务器添加新工具，随需求演进扩展 Agent 的能力；
- AI Toolkit 内置 MCP 服务器模板（如 Python 模板），让创建自定义工具变得很容易。
补充资源与下一步
- AI Toolkit 官方文档（
https://aka.ms/AIToolkit/doc） - 下一步：测试与调试
- 教程
- 文档
- 人工智能
【免费下载链接】mcp-for-beginners
This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.
相关推荐
使用 AI Toolkit for Visual Studio Code 消费 MCP 服务器：以计算器 Agent 为例
使用 AI Toolkit for Visual Studio Code 消费 MCP 服务器：以计算器 Agent 为例 本文基于 mcp for begin
教程文档人工智能在 Visual Studio Code 中使用 GitHub Copilot Agent 模式消费 MCP 服务器
在 Visual Studio Code 中使用 GitHub Copilot Agent 模式消费 MCP 服务器 Visual Studio Code 与
教程文档人工智能使用 Microsoft Foundry Toolkit 在 VS Code 中消费 MCP 计算器服务器：从 Agent 创建到自然语言调用工具
使用 Microsoft Foundry Toolkit 在 VS Code 中消费 MCP 计算器服务器：从 Agent 创建到自然语言调用工具 本教程基于开
教程文档人工智能
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
