MCP for Beginners 学习指南：一站式导航 Model Context Protocol 初学者课程仓库

• 教程
• 文档
• 人工智能

导读

本文是开源课程仓库「Model Context Protocol (MCP) for Beginners」的完整学习指南，目标读者是 AI 开发者、系统架构师与软件工程师。通过本指南，你将快速理解该仓库 12 大章节的组织逻辑、每个模块的核心知识点、可配套实战的多语言示例位置，以及官方 SDK、MCP 客户端、流行 MCP 服务器等生态资源的分布，从而制定一条从「入门 → 动手 → 进阶 → 生产落地」的高效学习路线。无论你使用 C#、Java、JavaScript、Python、TypeScript 还是 Rust，都能在这份导航中找到对应的动手路径。

仓库概览：一份面向实战的多语言 MCP 课程

Model Context Protocol（MCP，模型上下文协议）是 AI 模型与客户端应用之间进行标准化交互的框架协议。它最初由 Anthropic 创建，现由更广泛的 MCP 社区通过官方 GitHub 组织维护。该仓库提供的不是纯理论讲义，而是一套以真实、跨语言代码示例为核心的完整课程——覆盖 C#、Java、JavaScript、Python、TypeScript 与 Rust，聚焦从会话建立到服务编排的模块化、可扩展、安全 AI 工作流构建实战。

课程设计的核心理念是「理论先行、动手紧跟」：前两章建立协议认知与安全基线，第三章以 15 个渐进式小节带你从零搭建服务器与客户端，第四章落到多语言 SDK 的实用实现，第五章进入上下文工程、OAuth2、实时搜索、路由与扩缩容等生产级主题，最后通过案例研究、动手实验室与工具链把知识收敛到可交付的工程能力。

可视化课程地图

仓库根目录的 study_guide.md 提供了一张 Mindmap 形式的课程全景图，用于快速建立整体认知。将其翻译整理如下：

这张地图揭示了课程的双主线：一条是「协议深度」主线（00→05），从协议本身演进到生产级工程能力；另一条是「动手密度」主线（10→12），通过 4 实验室工作坊、13 实验室数据库集成路径与工具链，把知识固化为可运行的服务器。

仓库结构：十二大章节逐一解析

仓库按 00 到 12 编号组织为十二个主要部分，每一部分聚焦 MCP 的不同侧面。以下结合各章节仓库内的实际内容逐一展开。

00-Introduction：为什么需要标准化的 AI 集成

00-Introduction/README.md 回答「为什么 AI 应用需要标准」这一根本问题。生成式 AI 应用起步容易，但随着规模增长会出现多模型混用、工具碎片化、扩展困难等架构难题。MCP 的价值在于：

• 统一模型与工具的集成方式，替代每个工具-模型对一套自定义代码的脆弱模式；
• 让不同厂商的多个模型在同一生态中共存；
• 强调可扩展性、一致性与可复用性，并减少厂商锁定。

该章节还给出 MCP 的高层架构：Host（运行 AI 模型的应用，如 VS Code、Claude Desktop）→ Client（发起请求的协议组件）→ Server（提供上下文、工具与能力）。核心构件包括 Resources（资源）、Prompts（提示词模板）、Tools（可执行工具），以及 Elicitation（服务器主动向用户索取输入的机制）。同时明确：Sampling 与 Roots 已在 MCP2026-07-28中废弃，新实现应分别改为直接集成 LLM 提供商 API、以及通过工具参数/资源 URI/服务器配置传递路径。

01-CoreConcepts：核心概念与 2026-07-28 规范变更

01-CoreConcepts/README.md 深入讲解 MCP 的客户端-服务器架构、协议组件、消息模式与传输机制，并用 .NET、Java、Python、JavaScript 四种语言演示如何注册一个天气服务器及其工具。

该章节最值得关注的是对当前协议版本2026-07-28的同步说明：01-CoreConcepts/mcp-2026-07-28.md 详细记录了这份「自 MCP 发布以来最大的一次修订」——六个 SEP（规范增强提案）把协议核心改为无状态：

• 移除initialize/initialized握手与Mcp-Session-Id头：协议版本、客户端信息与能力改由每次请求的_meta携带，任何服务器实例都可以处理任意请求，水平扩展不再需要粘性路由与共享会话存储；
• 新增Mcp-Method与Mcp-Name请求头（Streamable HTTP 必需），让负载均衡器无需解析 JSON 体即可按操作路由；
• tools/list与资源读取结果携带ttlMs与cacheScope缓存元数据，客户端无需长连接即可知道列表结果的保鲜期；
• Extensions 成为一等公民：MCP Apps（服务器渲染的沙箱 iframe UI）与 Tasks（以tasks/get、tasks/update、tasks/cancel驱动任务句柄的服务器主导生命周期）作为本版本两个官方扩展发布；
• Roots、Sampling、Logging 与 Dynamic Client Registration 进入 Deprecated 状态，建议分别替换为工具参数/资源 URI、直接 LLM 集成、stderr/OpenTelemetry 与 Client ID Metadata Documents；
• 工具的inputSchema/outputSchema升级为完整JSON Schema 2020-12，缺失资源的错误码从 MCP 自定义的-32002改为 JSON-RPC 标准的-32602。

掌握这份变更文档，是理解仓库中「为何有些示例仍标注2025-11-25」的关键：这些示例保留为旧协议兼容性教学，而新代码应遵循无状态 API。

02-Security：AI 系统安全是第二优先级的刻意设计

02-Security/README.md 将安全置于课程第二章节，对齐微软「Secure by Design」原则。该章节系统覆盖：

• MCP 特有威胁：提示词注入（Prompt Injection）、工具投毒（Tool Poisoning）、会话劫持、混淆代理问题（Confused Deputy）、令牌透传（Token Passthrough）漏洞、越权与供应链安全；
• OWASP MCP Top 10 风险清单（MCP01 令牌管理不当 ~ MCP10 上下文注入与过度共享）及对应的 Azure 缓解手段；
• 强制性安全要求：MCP 服务器绝不能接受未明确签发给该服务器的令牌；必须校验令牌 audience 声明；会话 ID 必须加密安全且绑定用户身份；服务器不得依赖会话完成认证；
• 微软安全方案集成：Microsoft Prompt Shields、Azure Content Safety、GitHub Advanced Security，以及基于 Azure Entra ID 的 OAuth 2.1 认证。

配套文档非常完整，仓库内提供了：

• 02-Security/mcp-security-best-practices.md：MCP 实现完整安全最佳实践；
• 02-Security/azure-content-safety-implementation.md：Azure 内容安全集成的可运行示例；
• 02-Security/mcp-security-controls.md：最新安全控制与技术；
• 02-Security/mcp-best-practices.md：核心安全实践速查表；
• 02-Security/samples/cimd-dcr-auth/README.md：可运行的 TypeScript2026-07-28资源服务器示例，对比推荐的 Client ID Metadata Documents 与已废弃的 Dynamic Client Registration 回退方案。

03-GettingStarted：15 节渐进式动手入门

03-GettingStarted/README.md 是课程的动手核心，包含 15 个渐进小节，覆盖环境搭建、首个服务器、客户端开发、LLM 集成到部署的全流程：

环境准备要点（来自该章节 README）：准备所选语言（C#、Java、Python、TypeScript、JavaScript 之一）的开发环境与 IDE；使用 NuGet、Maven/Gradle、pip、npm/yarn 等包管理器；为计划使用的 AI 服务准备 API Key。官方 SDK 覆盖 C#（与微软协作维护）、Java（与 Spring AI 协作维护）、TypeScript、Python（FastMCP）、Kotlin、Swift、Rust、Go。注意：SDK 对2026-07-28的支持按语言独立推进，运行示例前请检查包版本与 SDK 发布说明。

该章节还附带每语言一套计算器示例：Java、.NET、JavaScript、TypeScript、Python。

04-PracticalImplementation：多语言 SDK 的实战落地

04-PracticalImplementation/README.md 将理论转化为可构建、可测试、可部署的工程实践，重点是：

• 官方 SDK 使用：C#（ModelContextProtocol NuGet 包）、Java with Spring（依赖 Project Reactor，支持强类型与响应式编程）、TypeScript、JavaScript、Python（asyncio/FastAPI 集成）；
• 服务器三大核心特性：Resources（文档库、知识库、结构化数据源）、Prompts（预定义对话模板、引导式交互模式）、Tools（数据处理、外部 API 集成、搜索能力）；
• API 管理：推荐以 Azure API Management 作为 MCP 服务器前置网关，统一处理限流、令牌管理、监控、负载均衡与安全；
• 远程部署：通过azd up一键将函数应用与 APIM 等资源部署到 Azure，并用npx @modelcontextprotocol/inspector连接 SSE 端点进行验证。

其中 04-PracticalImplementation/pagination/README.md 专门讲解游标分页：tools/list、resources/list、prompts/list、resources/templates/list均支持nextCursor分页；并提供 Python、TypeScript、Java 三种服务器实现、Python/TypeScript 客户端实现、懒加载迭代器模式、三种游标设计策略（索引式/ID 式/编码状态式）以及最佳实践。核心建议是在数据源处分页，而不是把所有结果载入内存后再客户端分页。

05-AdvancedTopics：生产级能力的 17 个专题

05-AdvancedTopics/README.md 汇集 17 个高级专题，覆盖企业集成与生产级设计：

• mcp-integration：MCP 服务器上云 Azure；
• mcp-multi-modality：音频、图像与多模态响应示例；
• mcp-oauth2-demo：最小 Spring Boot 应用，同时演示 OAuth2 授权服务器与资源服务器；
• mcp-root-contexts 与 mcp-sampling：2025-11-25遗留原语及其2026-07-28迁移方案；
• mcp-routing：不同类型路由；
• mcp-scaling：水平与垂直扩缩容；
• mcp-security：服务器安全加固；
• web-search-mcp：Python 服务器+客户端与 SerpAPI 集成，演示多工具编排；
• mcp-realtimestreaming 与 mcp-realtimesearch：实时数据流与实时搜索；
• mcp-security-entra：基于 Microsoft Entra ID 的认证；
• mcp-foundry-agent-integration：MCP 与 Microsoft Foundry 智能体集成；
• mcp-contextengineering：上下文优化与动态上下文管理；
• mcp-transport：自定义传输机制；
• mcp-protocol-features：进度通知、请求取消、资源模板与错误处理模式；
• mcp-adversarial-agents：让立场对立的两个智能体共享一套 MCP 工具集，通过结构化辩论捕捉幻觉、暴露边界用例。

注意：5.4（Roots）与 5.6（Sampling）在2026-07-28中已废弃，5.16 提到的实验性 Tasks 已迁入独立 Tasks 扩展，这些小节保留为2025-11-25遗留实现并附迁移指引。

06-CommunityContributions：社区生态参与

06-CommunityContributions/README.md 介绍如何贡献代码与文档、通过 GitHub 协作、使用多种 MCP 客户端（Claude Desktop、Cline、VSCode）以及接入包括图像生成在内的流行 MCP 服务器。

07-LessonsfromEarlyAdoption：早期采用者经验与微软服务器清单

07-LessonsfromEarlyAdoption/README.md 通过企业案例研究（客户支持自动化、医疗诊断助手、金融服务风险分析、Playwright 浏览器自动化、Azure MCP 服务、Microsoft Learn Docs 等）展示 MCP 的真实落地，并展望多模态 MCP、联邦 MCP 基础设施、MCP 市场等未来方向。

重点资源是 07-LessonsfromEarlyAdoption/microsoft-mcp-servers.md：一份10 个生产就绪微软 MCP 服务器的权威清单，包括：

08-BestPractices：性能、容错与韧性

08-BestPractices/README.md 关注生产质量：性能调优与优化、容错 MCP 系统设计、测试与韧性策略。其中 08-BestPractices/reliability-sidecars 以 Python 为例演示可靠性 sidecar 模式。

09-CaseStudy：七个完整案例研究

09-CaseStudy/README.md 收录七个体现 MCP 跨场景通用性的完整案例：

• Azure AI 旅行代理：Azure OpenAI + AI Search 的多智能体编排（travelagentsample.md）；
• Azure DevOps 集成：用 YouTube 数据更新自动化工作流（UpdateADOItemsFromYT.md）；
• 实时文档检索：带流式 HTTP 的 Python 控制台客户端（docs-mcp）；
• 交互式学习计划生成器：Chainlit 对话式 AI Web 应用；
• 编辑器内文档：VS Code 与 GitHub Copilot 工作流集成；
• Azure API 管理：企业 API 与 MCP 服务器创建（apimsample.md）；
• GitHub MCP 注册表：生态开发与智能体集成平台。

10 与 11：两套动手实验室体系

10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit（README）：将 MCP 与 AI 工具包结合的综合动手工作坊，4 个实验室依次覆盖 MCP 服务器基础、高级服务器开发、AI 工具包集成、生产部署与扩缩容，采用分步指令的实验室式学习。

11-MCPServerHandsOnLabs（README）：13 个实验室的完整学习路径，围绕Zava Retail 零售分析用例构建生产就绪的 PostgreSQL 集成 MCP 服务器：

• 实验室 00-03 基础：介绍、架构、安全、环境搭建；
• 实验室 04-06 构建服务器：数据库设计、MCP 服务器实现、工具开发；
• 实验室 07-09 高级特性：语义搜索、测试与调试、VS Code 集成；
• 实验室 10-12 生产与最佳实践：部署、监控、优化。

覆盖技术栈包括 FastMCP 框架、PostgreSQL、Azure OpenAI、Azure Container Apps、Application Insights，并融入行级安全（RLS）与多租户数据访问等企业级模式。

12-tooling：Copilot 应用中的 MCP

12-tooling/README.md 教你如何将 MCP 用于 Copilot 应用等工具，是该课程的收尾章节，把协议能力接入日常 AI 编程环境。

附加资源

仓库还提供以下辅助资源：

• images/ 图片目录：包含贯穿课程各章节的架构图与插画（如 prompt-injection.png 等安全攻击图、video-thumbnails 各章节视频缩略图）；
• translations/ 翻译目录：对文档提供多语言自动翻译支持（含中文 translations/zh-CN 等 60+ 语言）；
• 官方 MCP 资源：MCP 文档、2026-07-28规范与 MCP 官方仓库（可在 01-CoreConcepts/mcp-2026-07-28.md 的 Additional Resources 一节查看对应链接）。

如何高效使用本仓库

学习指南给出了五条使用路径，建议按需组合：

1. 顺序学习：按 00 到 12 章节顺序阅读，获得结构化学习体验——前 05 章建立协议与安全认知，后 07 章进入案例、实验室与工具实战；
2. 按语言聚焦：若只关心特定语言，直接前往samples目录查看对应语言的实现——仓库在 03-GettingStarted/samples 提供 Java、C#、JavaScript、TypeScript、Python 五套计算器示例，在 04-PracticalImplementation/samples 提供各语言的 MCP 服务器/客户端示例；
3. 实战优先：直接从「Getting Started」开始，搭建环境并创建第一个 MCP 服务器与客户端；
4. 进阶探索：掌握基础后进入 Advanced Topics，扩展路由、扩缩容、安全加固与上下文工程能力；
5. 社区参与：通过 GitHub 讨论与 Discord 频道与专家和同行开发者连接。

MCP 客户端与工具生态

课程覆盖了广泛的 MCP 客户端与工具，帮助你选择适合自己的开发与消费环境：

官方客户端：Visual Studio Code、VS Code 中的 MCP 支持、Claude Desktop、Claude in VSCode、Claude API。

社区客户端：Cline（终端型）、Cursor（代码编辑器）、ChatMCP、Windsurf。

MCP 管理工具：MCP CLI、MCP Manager、MCP Linker、MCP Router。

其中主机配置与调试的详细操作分别在 03-GettingStarted/12-mcp-hosts/README.md（传输类型与故障排查）与 03-GettingStarted/13-mcp-inspector/README.md（交互式调试）中有专题讲解。

流行 MCP 服务器速览

仓库介绍的 MCP 服务器可归为五类，可作为实验与集成的候选：

1. 官方微软服务器：上节已列出的 10 个生产就绪服务器（详见 07-LessonsfromEarlyAdoption/microsoft-mcp-servers.md）；
2. 官方参考服务器：Filesystem（文件系统）、Fetch、Memory（记忆）、Sequential Thinking（顺序思考）；
3. 图像生成：Azure OpenAI DALL-E 3、Stable Diffusion WebUI、Replicate；
4. 开发工具：Git MCP、Terminal Control（终端控制）、Code Assistant（代码助手）；
5. 专用服务器：Salesforce、Microsoft Teams、Jira & Confluence。

参与贡献

该仓库欢迎社区贡献。可参考 06-CommunityContributions/README.md 的贡献指南，了解如何为 MCP 生态有效贡献；同时遵循仓库根目录的 CODE_OF_CONDUCT.md、SECURITY.md 与 SUPPORT.md 相关规定。

版本说明：2026-07-28 规范下的课程现状

本学习指南最近更新于 2026 年 9 月 9 日，反映MCP 规范2026-07-28（当前协议修订版）的状态。需要特别留意两点：

• 部分动手示例仍明确版本化到2025-11-25（如第 3 章的 14-sampling 与第 5 章的 Roots/Sampling 专题），因其 SDK 尚未采用新的无状态 API——请将其视为遗留兼容性指引；
• 各 SDK 与工具正在逐步采用无状态协议 API，运行示例前务必核对对应 SDK 的版本与发布说明。

给读者的建议：以本指南为地图，先在 00-Introduction 建立协议认知，在 02-Security 建立安全基线，随后进入 03-GettingStarted/01-first-server 动手写出第一个服务器，再按你的语言偏好与业务目标选择进阶路线——无论是 04-PracticalImplementation 的 SDK 实战、05-AdvancedTopics 的专题深潜，还是 11-MCPServerHandsOnLabs 的 13 实验室生产路径，这条从会话建立到服务编排的完整学习链都已为你铺好。

• 教程
• 文档
• 人工智能