Python MCP Demos

Python MCP演示

一个演示项目，展示了使用FastMCP的模型上下文协议（MCP）实现，包括stdio和HTTP传输、与LangChain和代理框架的集成以及部署到Azure容器应用程序的示例。

目录

• 入门

- - VS代码开发容器 - 当地环境

• 运行本地MCP服务器

- - 使用VS代码进行调试 - 与MCP检查员一起检查 - 使用Aspire仪表板查看痕迹

• 运行本地代理\MCP
• 部署到Azure
• 通过专用网络部署到Azure
• 使用Keycloak身份验证部署到Azure
• 使用Entra OAuth代理部署到Azure
• 资源

入门

您有几个选项可以设置此项目。最快的入门方法是GitHub Codespace，因为它将为您设置所有工具，但您也可以在本地设置。

GitHub代码空间

您可以使用GitHub Codespace虚拟运行此项目。单击以下按钮之一，在浏览器中打开基于web的VS Code实例：

默认值（Azure OpenAI）：

](https://codespaces.new/Azure-Samples/python-mcp-demos)

Ollama（本地型号，需要64GB+内存）：

](https://codespaces.new/Azure-Samples/python-mcp-demos?devcontainer_path=.devcontainer/ollama/devcontainer.json)

Ollama Codespace预安装Ollama并拉取 gemma4:e2b 模型和副本 .env.sample.ollama 如你的 .env 文件。请注意，64GB的内存需求将更快地消耗您的代码空间配额。

打开代码空间后，打开终端窗口并继续执行部署步骤。

VS代码开发容器

一个相关的选项是VS代码开发容器，它将使用 开发容器扩展:

1. 启动Docker桌面（如果尚未安装，请安装）
2. 打开项目： 
3. 在打开的VS Code窗口中，一旦项目文件出现（这可能需要几分钟），打开一个终端窗口。
4. 继续执行部署步骤。

当地环境

如果你没有使用上述选项之一，那么你需要：

1. 确保安装了以下工具：

- Azure开发者命令行界面（azd） - Python 3.13+ - - Git

1. 克隆存储库并打开项目文件夹。

1. 创建一个 Python虚拟环境 并激活它。

1. 安装依赖项：

   uv sync

1. 复制 .env-sample 到 .env 并配置您的环境变量：

   cp .env-sample .env

1. 编辑 .env 使用您的API证书。通过设置选择以下提供程序之一 API_HOST:

- azure -Azure OpenAI（需要Azure凭据） - ollama -支持Responses API的本地Ollama实例 - openai -OpenAI API（需要 OPENAI_API_KEY)

运行本地MCP服务器

该项目包括MCP服务器 servers/ 目录：

本地服务器(basic_mcp_stdio.py 和 basic_mcp_http.py)使用工具实现“费用跟踪器”，将费用添加到CSV文件中。

与GitHub Copilot一起使用

这 .vscode/mcp.json 该文件为GitHub Copilot集成配置MCP服务器：

可用服务器：

• 费用mcp：用于生产的stdio传输服务器
• mcp调试费用：端口5678上带有调试程序的stdio服务器
• 费用mcp http：HTTP传输服务器位于 http://localhost:8000/mcp。您必须使用手动启动此服务器 uv run servers/basic_mcp_http.py 在使用它之前。

切换服务器：

通过打开聊天面板，选择工具图标，并从列表中选择所需的MCP服务器，配置GitHub Copilot使用的服务器。

Servers selection dialog

示例输入：

使用这样的查询来测试费用MCP服务器：

Log expense for 50 bucks of pizza on my amex today

使用VS代码进行调试

这 .vscode/launch.json 提供调试配置以连接到MCP服务器。

使用GitHub Copilot Chat调试MCP服务器：

1. 在MCP服务器代码中设置断点 servers/basic_mcp_stdio.py
2. 通过启动调试服务器 mcp.json 通过选择进行配置 expenses-mcp-debug
3. 按 Cmd+Shift+D 打开运行和调试
4. 选择“连接到MCP服务器（stdio）”配置
5. 按 F5 或单击播放按钮启动调试器
6. 在GitHub Copilot聊天工具中选择“experts mcp debug”服务器
7. 使用GitHub Copilot Chat触发MCP工具
8. 调试器在断点处暂停

与MCP检查员一起检查

这 MCP检查员 是一个用于测试和调试MCP服务器的开发工具。

注： 虽然HTTP服务器在技术上可以在代码空间/开发容器中处理端口转发，但MCP检查器和调试器附件的设置并不简单。为了获得具有完整调试功能的最佳开发体验，我们建议在本地运行此项目。

对于stdio服务器：

npx @modelcontextprotocol/inspector uv run servers/basic_mcp_stdio.py

对于HTTP服务器：

1. 启动HTTP服务器：

   uv run servers/basic_mcp_http.py

1. 在另一个终端中，运行检查器：

   npx @modelcontextprotocol/inspector http://localhost:8000/mcp

检查员提供了一个web界面，用于：

• 查看可用的工具、资源和提示
• 使用自定义参数调用测试工具
• 检查服务器响应和错误
• 调试服务器通信

使用Aspire仪表板查看痕迹

您可以使用 .NET Aspire仪表板 从MCP服务器查看OpenTetry跟踪、指标和日志。

注： Aspire Dashboard集成仅为HTTP服务器配置(basic_mcp_http.py).

1. 启动Aspire仪表板：

   docker run --rm -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
       mcr.microsoft.com/dotnet/aspire-dashboard:latest

> Aspire Dashboard在容器端口18889上公开了其OTLP端点。地图 -p 4317:18889 使其在主机的标准OTLP端口4317上可用。

从容器日志中获取仪表板URL和登录令牌：

   docker logs aspire-dashboard 2>&1 | grep "Login to the dashboard"

1. 通过将此添加到您的 .env 文件：

   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

1. 启动HTTP服务器：

   uv run servers/basic_mcp_http.py

1. 查看仪表板：http://localhost:18888

______________________________________________________________________

运行本地代理\MCP

该项目包括示例代理 agents/ 演示如何将AI代理连接到MCP服务器的目录：

要运行代理，请执行以下操作：

1. 首先启动HTTP MCP服务器：

   uv run servers/basic_mcp_http.py

1. 在另一个终端中，运行代理：

   uv run agents/agentframework_http.py

代理将连接到MCP服务器，并允许您通过聊天界面与费用跟踪工具进行交互。

______________________________________________________________________

部署到Azure

此项目可以使用Azure Developer CLI（azd）部署到Azure容器应用程序。部署规定：

• Azure容器应用 -同时托管MCP服务器和代理
• Azure OpenAI -为代理提供LLM
• Azure Cosmos数据库 -存储费用数据
• Azure容器注册表 -存储容器图像
• 日志分析 -监测和诊断

Azure帐户设置

1. 注册一个 免费Azure帐户 并创建Azure订阅。
2. 检查您是否具有必要的权限：

- 您的Azure帐户必须具有 Microsoft.Authorization/roleAssignments/write 权限，例如 基于角色的访问控制管理员, 用户访问管理员，或 拥有者. - 您的Azure帐户还需要 Microsoft.Resources/deployments/write 订阅级别的权限。

使用azd部署

1. 登录到Azure：

   azd auth login

对于GitHub Codespace用户，如果前面的命令失败，请尝试：

   azd auth login --use-device-code

1. 创建新的azd环境：

   azd env new

这将在内部创建一个文件夹 .azure 您的环境名称。

1. 提供和部署资源：

   azd up

它将提示您选择订阅和位置。这将需要几分钟才能完成。

1. 部署完成后，a .env 将创建一个文件，其中包含必要的环境变量，以便在部署的资源上本地运行代理。

成本

定价因地区和使用情况而异，因此无法预测您使用的确切成本。

你可以试试 Azure定价计算器 对于资源：

• Azure OpenAI服务：S0级，GPT-5.2型号。定价基于代币数量。 定价
• Azure容器应用：消费层。 定价
• Azure容器注册表：标准层。 定价
• Azure Cosmos数据库：无服务器层。 定价
• 日志分析 （可选）：按需付费。成本基于摄入的数据。 定价

⚠️ 为了避免不必要的成本，如果应用程序不再使用，请记住通过删除门户中的资源组或运行 azd down.

将部署的MCP服务器与GitHub Copilot一起使用

已部署的MCP服务器的URL在azd环境变量中可用 MCP_SERVER_URL，并写入 .env 部署后创建的文件。

1. 为避免冲突，请停止MCP服务器 mcp.json 并禁用GitHub Copilot聊天工具中的费用MCP服务器。

1. 从VS代码命令面板中选择“MCP:添加服务器”

1. 选择“HTTP”作为服务器类型

1. 根据以下内容输入MCP服务器的URL MCP_SERVER_URL 环境变量。

1. 在GitHub Copilot Chat工具中启用MCP服务器，并使用费用跟踪查询对其进行测试：

   Log expense for 75 dollars of office supplies on my visa last Friday

在本地运行服务器

部署设置了所需的Azure资源（Cosmos DB、Application Insights）后，您还可以在本地针对这些资源运行MCP服务器：

# Run the MCP server
cd servers && uvicorn deployed_mcp:app --host 0.0.0.0 --port 8000

在Azure应用程序洞察中查看跟踪

默认情况下，已部署的MCP服务器启用了OpenTetry跟踪，并将跟踪发送到Azure Application Insights。要打开指标和跟踪的仪表板，请运行：

azd monitor

或者，您可以直接使用Application Insights：

1. 打开Azure门户，导航到部署期间创建的Application Insights资源（名为 `

-appinsights`).

1. 在Application Insights中，转到“事务搜索”查看MCP服务器的跟踪。
2. 您可以过滤和分析跟踪以监控性能和诊断问题。

在Logfire中查看痕迹

您还可以在中查看OpenTetry跟踪 原木火 通过配置MCP服务器以在那里发送跟踪。

1. 创建一个Logfire帐户，并从Logfire仪表板获取您的写入令牌。

1. 设置azd环境变量以启用Logfire：

   azd env set OPENTELEMETRY_PLATFORM logfire
   azd env set LOGFIRE_TOKEN 

1. 提供和部署：

   azd up

1. 打开Logfire仪表板查看MCP服务器的跟踪。

______________________________________________________________________

通过专用网络部署到Azure

为了演示生产部署的增强安全性，此项目支持使用限制公共访问Azure资源的虚拟网络（ExpressRoute）配置进行部署。

1. 设置这些azd环境变量，为容器应用程序、Cosmos DB和OpenAI资源设置虚拟网络和私有端点：

   azd env set USE_VNET true
   azd env set USE_PRIVATE_INGRESS true

日志分析和ACR资源仍将启用公共访问，因此您可以在不需要VPN的情况下部署和监控应用程序。在生产中，您通常也会限制这些。

1. 提供和部署：

   azd up

私人网络的额外费用

当使用ExpressRoute配置时，会配置额外的Azure资源：

• 虚拟网络：现收现付。成本基于处理的数据。 定价
• Azure专用DNS解析程序：每月定价、端点和区域。 定价
• Azure专用端点：每个端点每小时定价。 定价

______________________________________________________________________

使用Keycloak身份验证部署到Azure

该项目支持使用Keycloak作为身份提供者，使用OAuth 2.0身份验证进行部署，实现 MCP OAuth规范 使用动态客户端注册（DCR）。

📺 观看Keycloak集成的演示视频

部署什么

部署步骤

1. 启用Keycloak身份验证：

   azd env set MCP_AUTH_PROVIDER keycloak

1. 设置Keycloak管理员密码（必填）：

   azd env set KEYCLOAK_ADMIN_PASSWORD "YourSecurePassword123!"

1. 可选地自定义领域名称（默认值： mcp):

   azd env set KEYCLOAK_REALM_NAME "mcp"

1. 部署到Azure：

   azd up

这将创建Azure容器应用程序环境，使用预配置的域部署Keycloak，使用OAuth验证部署MCP服务器，并配置基于HTTP路由的路由。

1. 通过检查输出来验证部署：

   azd env get-value MCP_SERVER_URL
   azd env get-value KEYCLOAK_DIRECT_URL
   azd env get-value KEYCLOAK_ADMIN_CONSOLE

1. 访问Keycloak管理控制台以验证域是否已配置：

   https:///auth/admin

使用...登录 admin 以及您配置的密码。

将Keycloak OAuth MCP服务器与GitHub Copilot结合使用

Keycloak部署支持动态客户端注册（DCR），这允许VS Code自动注册为OAuth客户端。VS代码重定向URI在Keycloak领域中预先配置。

要将部署的MCP服务器与GitHub Copilot Chat一起使用：

1. 为避免冲突，请停止MCP服务器 mcp.json 并禁用GitHub Copilot聊天工具中的费用MCP服务器。

1. 从VS代码命令面板中选择“MCP:添加服务器”

1. 选择“HTTP”作为服务器类型

1. 输入MCP服务器的URL azd env get-value MCP_SERVER_URL

1. 您应该看到浏览器中打开了Keycloak身份验证屏幕。选择“允许访问”：

Keycloak allow access screen

1. 使用Keycloak用户登录（例如。， testuser / testpass 对于预配置的演示用户）：

Keycloak sign-in screen

1. 身份验证后，浏览器将重定向回VS Code：

VS Code redirect after Keycloak sign-in

1. 在GitHub Copilot聊天工具中启用MCP服务器：

1. 使用费用跟踪查询进行测试：

   Log expense for 75 dollars of office supplies on my visa last Friday

1. 通过检查Cosmos数据库来验证费用是否增加 user-expenses Azure门户中的容器或通过询问GitHub Copilot Chat：

   Show me my expenses from last week

已知限制（演示权衡）

注： Keycloak必须可公开访问，因为其URL是由Azure动态生成的。令牌颁发者验证需要一个已知的URL，但mcproutes URL在部署后才可用。使用自定义域可以解决此问题。

______________________________________________________________________

使用Entra OAuth代理部署到Azure

此项目支持使用FastMCP内置的Azure OAuth代理进行Microsoft Entra ID（Azure AD）身份验证的部署。这是Keycloak的替代方案，它使用Microsoft Entra和Azure租户进行身份管理。

📺 观看Entra集成的演示视频

Entra OAuth部署了什么

Entra OAuth的部署步骤

1. 启用Entra OAuth代理：

   azd env set MCP_AUTH_PROVIDER entra_proxy

1. 设置租户ID，以便在正确的租户中创建应用程序注册：

   azd env set AZURE_TENANT_ID ""

1. 部署到Azure：

   azd up

部署期间：

- 预浸钩：使用客户端密钥创建Microsoft Entra应用程序注册，并将凭据存储在azd环境变量中 - 供应后挂钩：使用部署的服务器URL作为额外的重定向URI更新应用程序注册

1. 通过检查输出来验证部署：

   azd env get-value MCP_SERVER_URL
   azd env get-value ENTRA_PROXY_AZURE_CLIENT_ID

环境变量

以下环境变量由部署挂钩自动设置：

然后将其写入 .env 通过后视觉挂钩进行局部开发。

在本地测试Entra OAuth服务器

部署后，您可以在启用OAuth的情况下进行本地测试：

# Run the MCP server
cd servers && uvicorn auth_entra_mcp:app --host 0.0.0.0 --port 8000

服务器将使用OAuth的Entra应用程序注册和CosmosDB进行客户端存储。

使用Entra OAuth MCP服务器和GitHub Copilot

Entra应用程序注册包括以下VS代码的重定向URI：

• https://vscode.dev/redirect （VS代码网）
• http://127.0.0.1:{33418-33427} （VS Code桌面本地身份验证助手，10个端口）

要将部署的MCP服务器与GitHub Copilot Chat一起使用：

1. 为避免冲突，请停止MCP服务器 mcp.json 并禁用GitHub Copilot聊天工具中的费用MCP服务器。

1. 从VS代码命令面板中选择“MCP:添加服务器”

1. 选择“HTTP”作为服务器类型

1. 输入MCP服务器的URL，可以从 MCP_SERVER_URL 环境变量或 http://localhost:8000/mcp 如果在本地运行。

1. 如果收到“找不到客户端ID”的错误，请打开命令面板，运行 “身份验证：删除动态身份验证提供程序”，并选择MCP服务器URL。这将清除所有缓存的OAuth令牌并强制执行新的身份验证流。然后重新启动服务器以再次提示OAuth流。

1. 您应该看到浏览器中打开了FastMCP身份验证屏幕。选择“允许访问”：

FastMCP authentication screen

1. 授予访问权限后，浏览器将重定向到VS Code“登录成功！”页面，然后将焦点带回VS Code。

VS Code sign-in successful page

1. 在GitHub Copilot Chat工具中启用MCP服务器，并使用费用跟踪查询对其进行测试：

   Log expense for 75 dollars of office supplies on my visa last Friday

1. 通过检查Cosmos数据库来验证费用是否增加 user-expenses Azure门户中的容器。

Cosmos DB user-expenses container

资源

• 视频系列：Python+MCP（2025年12月）
• 博客文章：为基于Entra的MCP服务器使用代表流
• MCP初学者：在线教程
• Azure Functions上的Python MCP服务器