模型上下文协议（MCP）让大语言模型（LLM, Large Language Model）具备直接操作外部系统的能力，使智能体从对话系统进化为行动系统。本章通过示例展示如何从零构建、连接与部署 MCP 服务器和客户端，涵盖从工具开发、远程调用、IDE 集成到安全规范的完整流程。
构建你的第一个 MCP 服务器：天气查询示例
MCP 服务开发通常从简单的工具型服务入手。下方流程图展示了天气查询 MCP 服务器的开发步骤：
【iframe defaul_iframe_type】https://assets.jimmysong.io/images/book/ai-handbook/mcp/development/3cc704461df5cb618eb3bb7f56cdaf39.svg
图 1: 天气查询 MCP 服务器开发流程
下面是使用 FastMCP 快速实现天气查询服务器的代码示例：
from fastmcp import mcp, toolimport httpx
@tool(name="get_alerts", description="查询指定地区的天气预警")async def get_alerts(zone: str): async with httpx.AsyncClient() as client: url = f"https://api.weather.gov/alerts/active/zone/{zone}" resp = await client.get(url) data = resp.json() return {"type": "text", "text": f"{len(data['features'])} 条预警"}
@tool(name="get_forecast", description="获取七天天气预报")async def get_forecast(lat: float, lon: float): async with httpx.AsyncClient() as client: url = f"https://api.weather.gov/points/{lat},{lon}/forecast" resp = await client.get(url) forecast = resp.json()['properties']['periods'] text = "n".join([f"{p['name']}: {p['detailedForecast']}" for p in forecast]) return {"type": "text", "text": text}
if __name__ == "__main__": mcp.run(transport="stdio")STDIO 模式注意事项
在 STDIO 模式下，严禁直接向标准输出打印非 JSON 数据。日志请使用
stderr或专用日志库。
使用参考服务器
MCP 官方与社区已提供丰富的参考服务器，可直接学习其实现方式。下表总结了常用参考服务器类别与功能：
| 类别 | 服务器 | 功能 |
| 基础能力 | server-filesystem | 以安全方式读写本地文件系统 |
| 记忆模块 | server-memory | 存储上下文记忆与知识图谱 |
| 协作平台 | server-github | 访问代码仓库、提交 PR、搜索文件 |
| 时间/系统工具 | server-clock、server-env | 提供时间、环境变量访问能力 |
表 1: MCP 参考服务器类别与功能
下面是 Claude Desktop / MCP Client 的参考服务器配置示例：
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "<你的 token>"} } }}这些参考实现展示了工具（tools）、资源（resources）与提示（prompts）的完整结构，是学习 MCP 设计规范的最佳入口。
连接远程 MCP 服务器
远程服务器将 SaaS 服务以 MCP 接口形式暴露。下表总结了常见平台及其功能：
| 平台 | 功能 |
| Asana / Linear / Jira | 创建任务、同步进度 |
| Intercom / Slack | 客服对话与事件推送 |
| PayPal / Stripe / Plaid | 支付、退款与对账 |
表 2: 常见远程 MCP 服务器平台与功能
下面是 Claude API 的远程 MCP 服务器请求示例：
{ "model": "claude-3-sonnet-20240229", "messages": [...], "mcp_servers": [ { "url": "https://mcp.asana.com/sse", "name": "asana", "allowed_tools": ["create_task", "list_tasks"] } ]}远程服务器安全提示
远程服务器非官方运营，连接前务必审查其安全策略与隐私条款，仅信任受验证的端点。
搭建自定义 MCP 服务器
MCP Server 的核心职责是通过 JSON-RPC 协议定义工具、资源与提示，使模型可通过标准接口调用外部系统。下表总结了主流语言及其框架：
| 语言 | 框架 / 库 | 特性 |
| Python | fastmcp, mcp-fastapi | 装饰器定义工具，支持 stdio / HTTP 模式 |
| TypeScript | @anthropic-ai/mcp | 官方 SDK，支持快速定义与运行 |
| C# / .NET | McpSharp | 类型安全与依赖注入 |
| Rust | mcp-rs | 异步高性能实现，适合服务端部署 |
表 3: 主流 MCP Server 框架与特性
Python + FastMCP 实战示例
下面代码展示了如何用 FastMCP 实现文件检索与搜索工具：
from fastmcp.server import MCPServer, tool, resource
@resource(name="project_files", description="用户项目目录", path="/home/user/project", writable=False)def project_files(): pass
@tool(name="search_in_file", description="在文件中搜索关键词")def search_in_file(filename: str, keyword: str) -> str: with open(filename) as f: lines = [line for line in f if keyword in line] return "n".join(lines) or "未找到"
if __name__ == "__main__": server = MCPServer(tools=[search_in_file], resources=[project_files]) server.run_stdio()运行后，该服务将向客户端暴露：
- 一个可列出
/home/user/project文件的资源；
- 一个
search_in_file工具，可在文件内搜索关键词。
Playwright MCP 与 Context7：生态型实践
MCP 生态中有多种工具型与资源型服务器。下表总结了典型项目及其功能定位：
| 项目 | 类型 | 功能定位 |
| Playwright MCP | 工具型 Server | 网页交互与自动化测试 |
| Context7 | 资源型 Server | 实时代码文档检索 |
表 4: 生态型 MCP 项目与功能定位
Playwright MCP 提供浏览器操作能力（基于 Accessibility Tree），支持打开网页、操作 DOM、执行 E2E 测试、生成测试脚本与 UI 检查。下方时序图展示了自动化测试流程：
【iframe defaul_iframe_type】https://assets.jimmysong.io/images/book/ai-handbook/mcp/development/4144fc45f81bc8fc42c453bf7f4cc54d.svg
图 2: Playwright MCP 自动化测试流程
Context7 为模型提供实时、版本对应的代码文档检索，常用于框架 API 对齐、文档到代码自动联动、RAG for Docs 场景。
VS Code 集成 Playwright MCP：端到端实践
VS Code 集成 Playwright MCP 可实现自动化测试与脚本生成。下表总结了集成流程与关键操作：
| 步骤 | 操作 |
| 安装 @playwright/mcp：npm install @playwright/mcp | |
| 在 .vscode/mcp.json 中配置服务器 | |
| 运行站点（npm run dev）并通过 Chat 指令触发测试 | |
| VS Code 会提示授权执行浏览器操作 | |
| 测试脚本生成于 tests/ 目录，可复运行或回放 |
表 5: VS Code 集成 Playwright MCP 流程
安全与工程规范
MCP 开发需遵循安全守则与工程规范。下表总结了关键建议：
| 关键点 | 建议 |
| 最小权限 | 仅暴露必要路径和 API |
| 日志与审计 | 记录调用历史，便于追踪 |
| 数据脱敏 | 敏感资源仅允许只读访问 |
| 认证机制 | 支持 OAuth2 / JWT |
| 协作控制 | 通过 Zen MCP 等工具统一调度多个模型 |
| 异步框架 | 使用 asyncio / FastAPI 提升并发性能 |
| 输入输出 | 严格定义 JSON Schema |
| STDIO 输出 | 禁止非 JSON 调试输出 |
| 提示模板 | 结合 prompts 引导模型调用逻辑 |
| 错误处理 | 遵循 JSON-RPC 错误规范 |
表 6: MCP 安全与工程规范建议
客户端开发与集成流程
MCP 客户端开发流程包括初始化、工具查询、Prompt 构建、调用与响应解析。下方流程图展示了完整流程：
【iframe defaul_iframe_type】https://assets.jimmysong.io/images/book/ai-handbook/mcp/development/bc4eb545605bcdd15b67393fe9de78d4.svg
图 3: MCP 客户端开发与集成流程
客户端开发步骤：
- 初始化连接（stdio 或 HTTP）；
- 查询可用工具；
- 构建 Prompt 模板；
- 发送 JSON-RPC 调用；
- 接收结果并交由模型解释。
总结
MCP 的出现让模型首次具备操作系统层的可编程性。通过少量代码，开发者即可让 AI：
- 查询实时数据
- 操作文件与数据库
- 执行自动化测试
- 调用外部 SaaS 服务
核心价值：
- 标准化：统一工具调用语义
- 可组合：多 Server 协作组成 AI 应用
- 可扩展：支持跨语言、跨运行时
- 可控与可观测：具备企业级安全与审计能力
MCP 不只是协议，更是下一代智能体的运行时标准。
