Semantic Kernel Python 中的 MCP 客户端集成实战将 MCP Server 转化为内核插件【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 python/samples/concepts/mcp/README.md 展开系统讲解在 Semantic Kernel Python 中如何以MCP 客户端身份消费 Model Context ProtocolMCPServer通过MCPStdioPlugin、MCPSsePlugin、MCPStreamableHttpPlugin等类把远程或本地的 MCP Server 暴露出的Tools 与 Prompts 自动转换为 Semantic Kernel 的 Plugin进而被聊天、Agent 的函数调用Function Calling机制驱动。读完本文你将掌握pip install semantic-kernel[mcp]的安装方式、三种主流传输stdio / SSE / Streamable HTTP的插件接入方法、GitHub MCP Server 与本地uv服务的实际配置以及 sampling采样等进阶能力的调用细节。MCP 与 Semantic Kernel客户端/服务器双向定位Model Context Protocol 是由 Anthropic 提出的开放标准用于让模型Model之间、应用与模型之间共享上下文。协议体系由客户端client与服务器server构成MCP Server提供工具tools、提示词prompts、资源resources等服务端能力可以托管在本地如 stdio 子进程也可以作为在线 API 暴露MCP Client连接服务器、发现并调用上述能力。Semantic Kernel 的目标是同时扮演客户端与服务器两种角色作为客户端读取某个 MCP Server 的定义将其转换为 Semantic Kernel Plugin服务器暴露的 Tools 与 Prompts 会以 Kernel 函数的形式出现在内核中可被聊天或 Agent 的函数调用直接使用——这正是本文聚焦的python/samples/concepts/mcp/目录所演示的内容作为服务器反向把 Semantic Kernel 的 Agent/Plugin 暴露给外部 MCP Host如 Claude Desktop、VS Code Copilot Agents对应实现位于 python/samples/demos/mcp_server/ 目录。两种 Server 类型与四种插件类原文档明确区分了两类 MCP Server并从源码结构看python/semantic_kernel/connectors/mcp.py 中提供了四种对应的插件类插件类适用传输/场景典型启动方式MCPStdioPlugin基于标准输入输出stdio的本地子进程服务器npxNode 生态、uvx/uvPython 生态、docker run容器化MCPSsePlugin基于 Server-Sent EventsSSE的 HTTP 服务器服务器提供一个 URLMCPStreamableHttpPlugin基于 Streamable HTTP 传输的服务器如https://learn.microsoft.com/api/mcp服务器提供一个 URLMCPWebsocketPlugin基于 WebSocket 传输的服务器服务器提供一个 URL其中MCPSsePlugin与MCPStreamableHttpPlugin用法完全一致只需传入url参数即可见 agent_with_http_mcp_plugin.py。代码对两种服务器完全通用本地 stdio 服务器换用远程 SSE/HTTP 服务器时仅需替换插件类与连接参数。MCPPluginBase 公共参数所有插件类均继承自MCPPluginBasemcp.py 第 236 行起公共初始化参数包括参数默认值说明name必填插件名进入 Kernel 后成为函数命名空间前缀如Github-*descriptionNone插件描述供模型理解插件用途load_toolsTrue是否把 MCP Server 的 tools 加载为 Kernel 函数load_promptsTrue是否把 MCP Server 的 prompts 加载为 Kernel 函数sessionNone可复用的 MCPClientSessionkernelNone提供聊天补全客户端的 Kernel 实例供 sampling 回调用request_timeoutNone所有请求的默认超时sampling_consent_callbackNonesampling 请求的审批回调返回False则拒绝优先级高于sampling_auto_approvesampling_auto_approveFalse未配置回调时是否自动批准 sampling 请求仅在连接可信服务器时才应设为True从源码看插件通过AsyncExitStack管理生命周期__aenter__/connect()负责建立传输、创建ClientSession并session.initialize()__aexit__/close()负责发信号并关闭会话mcp.py 第 285-355 行。连接失败会抛出KernelPluginInvalidConfigurationError提示检查配置。运行环境准备在运行 python/samples/concepts/mcp 目录中的示例前按以下步骤准备按示例类型安装运行器使用 GitHub MCP Server 的示例需要 Docker Desktop容器化运行服务器使用本地 MCP Server 的示例需要安装 uv用于运行 Python 服务器确保npx、uvx或docker位于你的PATH中。GitHub MCP Server 需要 GitHub Personal Access TokenPAT该 Token 通过环境变量GITHUB_PERSONAL_ACCESS_TOKEN注入容器创建方法见 GitHub MCP Server 官方文档。核对示例文件头部注释每个示例开头都注明了需要设置的对应环境变量如OPENAI_API_KEY、AZURE_OPENAI_CHAT_DEPLOYMENT_NAME、AZURE_AI_AGENT_PROJECT_CONNECTION_STRING等。安装带 mcp extra 的 Semantic Kernelpip install semantic-kernel[mcp]运行示例cd python/samples/concepts/mcp python name.py示例全景8 个客户端集成脚本python/samples/concepts/mcp 目录围绕作为 MCP 客户端提供了 8 个示例覆盖不同服务后端与场景示例文件后端/服务演示要点mcp_as_plugin.pyOpenAI 兼容服务 GitHub MCP ServerDocker最基础的Plugin 即 MCP Server模式agent_with_mcp_plugin.pyAzure OpenAI GitHub MCP ServerDockerChatCompletionAgent使用 MCP 插件查询 issueagent_with_mcp_agent.pyAzure OpenAI 两个本地uvMCP Server多 MCP 插件 TimePlugin组合的订餐助手agent_with_mcp_sampling.pyOpenAI 本地 sampling MCP Server演示 MCP sampling 能力agent_with_http_mcp_plugin.pyAzure OpenAI Streamable HTTP 服务器MCPStreamableHttpPlugin远程接入local_agent_with_local_server.pyOllama本地模型 两个本地 MCP Server本地模型 MCP 的完全本地化方案azure_ai_agent_with_mcp_plugin.pyAzure AI Foundry Agent GitHub MCP ServerAzureAIAgent使用 MCP 插件做 issue 分诊azure_ai_agent_with_local_server.pyAzure AI Foundry Agent 两个本地 MCP ServerAzureAIAgent流式调用多插件基础用法mcp_as_plugin.py 逐段解析mcp_as_plugin.py 是最直观的入门示例——构建一个能回答 Microsoft semantic-kernel 项目问题的 GitHub 聊天机器人。核心流程如下1. 创建内核与聊天服务kernel Kernel() chat_service, settings get_chat_completion_service_and_request_settings(Services.OPENAI) settings.function_choice_behavior FunctionChoiceBehavior.Auto() kernel.add_service(chat_service)FunctionChoiceBehavior.Auto()默认auto_invokeTrue即模型会自动选择并调用所需函数。示例注释列出了支持函数调用的服务OPENAI、AZURE_OPENAI、AZURE_AI_INFERENCE、ANTHROPIC、BEDROCK、GOOGLE_AI、MISTRAL_AI、OLLAMA、ONNX、VERTEX_AI、DEEPSEEK。2. 用 MCP Server 定义创建插件async with MCPStdioPlugin( nameGithub, descriptionGithub Plugin, commanddocker, args[run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, ghcr.io/github/github-mcp-server], env{GITHUB_PERSONAL_ACCESS_TOKEN: os.getenv(GITHUB_PERSONAL_ACCESS_TOKEN)}, ) as github_plugin: kernel.add_plugin(github_plugin)关键点commandargs指定启动 MCP Server 的完整命令这里通过docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server在交互模式下运行官方 GitHub MCP Server 镜像env把宿主机环境变量透传给子进程/容器使用异步上下文管理器async with即可自动连接与关闭也可显式调用await github_plugin.connect()与await github_plugin.close()。3. 进入聊天循环while chatting: chatting await chat()chat()将用户输入加入ChatHistory调用chat_service.get_chat_message_content(history, settings, kernelkernel)模型按需触发 MCP 工具并返回结果。调试时可通过logging.getLogger(semantic_kernel.connectors.mcp).setLevel(logging.DEBUG)打开 MCP 连接日志。Agent 场景agent_with_mcp_plugin.pyagent_with_mcp_plugin.py 展示把 MCP 插件挂到ChatCompletionAgent上用AzureChatCompletion查询 GitHub issueagent ChatCompletionAgent( serviceAzureChatCompletion(credentialAzureCliCredential()), nameIssueAgent, instructionsAnswer questions about the Microsoft semantic-kernel github project., plugins[github_plugin], )其调用模式值得注意线程管理thread: ChatHistoryAgentThread | None None首次调用未传线程时自动创建响应中携带response.thread供下一轮复用多轮对话对预设的USER_INPUTS逐条调用agent.get_response(messagesuser_input, threadthread)清理结束前await thread.delete()。示例输出显示 Agent 能列出最新 5 个 Python issue、回答是否存在未分诊untriagedissue、查询指定 issue 状态——这些能力全部来自 GitHub MCP Server 暴露的工具。多插件编排agent_with_mcp_agent.pyagent_with_mcp_agent.py 演示一个订餐助手同时接入两个本地 MCP Server菜单查询与餐厅预订以及内置TimePluginasync with ( MCPStdioPlugin( nameMenu, descriptionMenu plugin, for details about the menu, call this plugin., commanduv, args[ f--directory{str(Path(os.path.dirname(__file__)).joinpath(servers))}, run, menu_agent_server.py, ], env{ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: os.getenv(AZURE_OPENAI_CHAT_DEPLOYMENT_NAME), AZURE_OPENAI_ENDPOINT: os.getenv(AZURE_OPENAI_ENDPOINT), }, ) as restaurant_agent, MCPStdioPlugin( nameBooking, descriptionRestaurant Booking Plugin, commanduv, args[ f--directory{str(Path(os.path.dirname(__file__)).joinpath(servers))}, run, restaurant_booking_agent_server.py, ], env{ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: os.getenv(AZURE_OPENAI_CHAT_DEPLOYMENT_NAME), AZURE_OPENAI_ENDPOINT: os.getenv(AZURE_OPENAI_ENDPOINT), }, ) as booking_agent, ): agent ChatCompletionAgent( serviceAzureChatCompletion(credentialAzureCliCredential()), namePersonalAssistant, instructionsHelp the user with restaurant bookings., plugins[restaurant_agent, booking_agent, TimePlugin()], )这些本地 MCP Server 本身是用agent.as_mcp_server()把 Semantic Kernel Agent 暴露为 MCP Server的见 servers/menu_agent_server.py其内部RestaurantPlugin用kernel_function定义list_restaurants、get_specials、get_item_price。示例输出展示了一次完整的多轮订餐列出餐厅 → 查询特价 → 询价 → 预订 → 时间冲突时尝试备选餐厅并最终确认说明模型能在多个 MCP 插件与本地函数之间自由编排。HTTP 远程接入agent_with_http_mcp_plugin.py当 MCP Server 以在线 API 暴露时无需本地启动进程直接使用MCPStreamableHttpPluginasync with MCPStreamableHttpPlugin( nameLearnSite, descriptionLearn Docs Plugin, urlhttps://learn.microsoft.com/api/mcp, ) as learn_plugin: agent ChatCompletionAgent( serviceAzureChatCompletion(credentialAzureCliCredential()), nameDocsAgent, instructionsAnswer questions about the Microsofts Semantic Kernel SDK., plugins[learn_plugin], )这是 agent_with_http_mcp_plugin.py 的核心仅凭一个 URL 即可把微软 Learn 文档站的 MCP 端点接入 Agent用于回答 SK SDK 相关问题——本地服务器与远程服务器在代码层面只有插件类与参数的差别。同样的模式适用于MCPSsePluginSSE 传输。本地化部署local_agent_with_local_server.pylocal_agent_with_local_server.py 展示完全本地的组合本地模型Ollama 本地 MCP Server。它同时加载 GitHubDocker与 ReleaseNotesuv运行的本地 Prompts 服务器两个插件使用OllamaChatCompletion作为服务agent ChatCompletionAgent( serviceOllamaChatCompletion(), nameGithubAgent, instructions..., plugins[github_plugin, release_notes_plugin], function_choice_behaviorFunctionChoiceBehavior.Auto( filters{ included_functions: [ Github-list_issues, ReleaseNotes-release_notes_prompt, ] } ), )值得注意的两点函数白名单过滤示例注释说明本地模型在函数过多时容易出问题因此通过FunctionChoiceBehavior.Auto(filters{included_functions: [...]})只保留Github-list_issues与ReleaseNotes-release_notes_prompt两个函数降低本地模型的选择负担流式输出使用agent.invoke_stream(messages..., thread..., argumentsKernelArguments(ownermicrosoft, reposemantic-kernel))逐块打印响应——KernelArguments可为 MCP 工具提供默认参数如仓库的 owner/repo。MCP Sampling 能力agent_with_mcp_sampling.pyagent_with_mcp_sampling.py 演示了 MCP 协议的sampling采样扩展MCP Server 在生成发布说明时反向请求客户端Agent调用大模型。接入方式是在插件上开启自动批准async with MCPStdioPlugin( nameReleaseNotes, descriptionSK Release Notes Plugin, commanduv, args[ f--directory{str(Path(os.path.dirname(__file__)).parent.parent.joinpath(demos, mcp_server))}, run, mcp_server_with_sampling.py, ], sampling_auto_approveTrue, ) as plugin:对应服务器端实现是 python/samples/demos/mcp_server/mcp_server_with_sampling.py。结合 mcp.py 源码 可以理解其安全模型默认sampling_auto_approveFalse未提供审批回调时 sampling 请求会被直接拒绝设置sampling_auto_approveTrue会自动批准请求首次会记录一条 warning 日志更精细的控制是传入sampling_consent_callback——该回调接收插件名与 sampling 请求参数返回False即拒绝且优先级高于sampling_auto_approve在MCPPluginBase.__init__注释中明确建议sampling_auto_approve仅在连接可信 MCP Server 时才应设为True。示例中 Agent 的指令要求先调用release_notes_prompt获取更完整的提示词再调用run_prompt生成最终输出并原样返回输出展示了由 PR 消息列表生成结构化发布说明的全过程——这是模型↔服务器↔模型三方协作的典型 MCP 应用。Azure AI Foundry Agent 集成MCP 插件同样适用于 Azure AI Foundry Agent。两个示例的区别仅在于服务器来源azure_ai_agent_with_mcp_plugin.py接入 Docker 运行 GitHub MCP Server创建issue 分诊 Agent能从未分诊、未分配的 issue 中根据近期 PR 活动给出 assignee 建议azure_ai_agent_with_local_server.py同时接入 GitHub 与 ReleaseNotes 两个 MCP 插件以流式方式输出 issue 列表与发布说明。两者均需设置环境变量AZURE_AI_AGENT_PROJECT_CONNECTION_STRINGyour azure connection string AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAMEyour azure model deployment name接入方式与ChatCompletionAgent一脉相承先AzureAIAgent.create_client(credentialcreds)创建客户端再把MCPStdioPlugin传入AzureAIAgent(..., plugins[...])。注意线程类型为AzureAIAgentThread结束清理时还需await client.agents.delete_agent(agent.definition.id)删除云端的 Agent 定义。反向视角把 Semantic Kernel 暴露为 MCP Server原文档指出反向能力Semantic Kernel 作为服务器位于 python/samples/demos/mcp_server/ 目录与客户端示例形成闭环。其中sk_mcp_server.py通用服务器入口agent_as_server.py把 Agent 暴露为服务器mcp_server_with_prompts.py 与 mcp_server_with_sampling.py演示 Prompts 与 sampling 扩展。以 servers/menu_agent_server.py 为例agent.as_mcp_server()一行即可生成服务器其头部注释给出了配置 MCP Host如 Claude Desktop、VS Code Copilot Agents的 JSON 模板并说明 SSE 模式可运行uv ... run agent_mcp_server.py --transport sse --port 8000监听 8000 端口。客户端示例中的本地服务器正是通过这一机制供uv启动的两个目录共同诠释了 Semantic Kernel 的客户端 服务器双角色目标。小结与实践建议综合原文档与仓库实现可将 MCP 客户端集成的实践要点归纳如下选对插件类本地子进程用MCPStdioPlugin配command/args/env远程 HTTP 服务按传输类型用MCPSsePlugin或MCPStreamableHttpPlugin配urlWebSocket 场景用MCPWebsocketPlugin管理好生命周期优先使用async with上下文管理器或在程序中显式connect()/close()确保子进程与会话被正确回收控制函数暴露范围模型对过多工具敏感时用FunctionChoiceBehavior.Auto(filters{included_functions: [...]})做白名单过滤尤其适用于本地小模型谨慎开启 sampling仅对可信服务器设置sampling_auto_approveTrue生产环境优先实现sampling_consent_callback做人工/策略审批从最小示例开始先跑通 mcp_as_plugin.py再按需演进到 Agent 编排agent_with_mcp_agent.py、远程 HTTPagent_with_http_mcp_plugin.py与 Azure AI Foundry 场景即可在 Semantic Kernel 生态中自由消费整个 MCP 工具生态。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考