MCP (Model Context Protocol) 完全指南

2025年12月更新Anthropic

MCP（模型上下文协议） 是 Anthropic 于 2024年11月推出的开放标准，被称为"AI 应用的 USB-C 接口"。它为 AI 模型连接外部系统提供了统一、安全、双向的通信协议。本指南基于 Anthropic Engineering 系列技术文章整理。

一、什么是 MCP？

1.1 核心定义

MCP (Model Context Protocol) 是一个开放标准和开源框架，用于：

能力	说明
统一连接	AI 模型与外部系统的标准化接口
双向通信	不仅读取数据，还能执行操作
安全访问	内置认证和权限控制
动态上下文	实时获取最新信息

1.2 解决的问题

之前的问题：碎片化集成

⚠️ 问题

每个数据源需要单独开发集成，耗时数周

MCP 的解决方案：统一协议

✅ 优势：一次开发，处处使用

1.3 核心价值

价值	说明
开发效率	集成时间从数周缩短到数天
跨模型移植	换 LLM 无需重写集成代码
生态共享	社区共建的 MCP Server 库
安全标准	统一的认证和权限机制

二、核心架构

2.1 三层架构

2.2 三大核心原语

原语	说明	示例
Tools（工具）	可执行的操作接口	航班搜索、数据库查询、发送消息
Resources（资源）	静态数据或元信息	机场代码列表、配置文件、文档
Prompts（提示词）	预定义的指令模板	代码审查模板、分析框架

三、工作流程

3.1 典型交互流程

步骤	说明
1️⃣ 用户输入	"帮我查询北京到上海明天的航班"
2️⃣ LLM 分析	识别需要调用航班搜索工具
3️⃣ Client 请求	调用 flight_search MCP Server
4️⃣ Server 执行	查询航空公司 API，返回结果
5️⃣ 结果返回	航班列表数据
6️⃣ 生成回复	"明天北京到上海有以下航班..."

四、代码执行模式（Code Mode）

4.1 传统模式的问题

随着 MCP 使用规模扩大，两种常见模式会增加 Agent 成本和延迟：

问题	说明
工具定义过载	多个 MCP Server 的工具定义可能消耗 100K+ tokens（开始对话前就已消耗）
中间结果膨胀	每个工具结果都要进入模型上下文，大文档可能重复处理多次

示例：将会议记录从 Google Drive 附加到 Salesforce

传统模式：
1. TOOL CALL: gdrive.getDocument → 返回完整文档（进入上下文）
2. TOOL CALL: salesforce.updateRecord → 需要再次写出完整文档

问题：2小时的销售会议 = 额外处理 50,000+ tokens

4.2 代码执行模式解决方案

将 MCP Server 呈现为代码 API 而非直接工具调用，Agent 通过编写代码与 MCP Server 交互：

typescript

// 代码执行模式 - 数据在执行环境中流动，不进入模型上下文
import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

const transcript = (await gdrive.getDocument({ documentId: 'abc123' })).content;
await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

4.3 工具发现机制

Agent 通过文件系统按需发现工具：

servers/
├── google-drive/
│   ├── getDocument.ts
│   ├── getSheet.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── slack/
    └── ...

对比	Token 消耗
传统方式（加载所有工具定义）	~150,000 tokens
代码执行模式（按需加载）	~2,000 tokens
节省	98.7%

4.4 代码执行模式的优势

优势	说明
渐进式披露	按需读取工具定义，而非全部预加载
上下文高效	在代码中过滤/处理数据，只返回精简结果
更强的控制流	循环、条件、错误处理用代码表达，减少模型调用
隐私保护	中间结果留在执行环境，敏感数据可自动脱敏
状态持久化	Agent 可将中间结果写入文件，支持长任务恢复
技能积累	Agent 可将工作代码保存为可复用函数

数据过滤示例：

typescript

// 传统模式 - 10,000 行全部进入上下文
TOOL CALL: gdrive.getSheet(sheetId: 'abc123') → 返回 10,000 行

// 代码执行模式 - 只返回需要的数据
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(row => row["Status"] === 'pending');
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // 只显示前 5 条

注意

代码执行引入额外复杂度，需要安全的执行环境（沙箱）、资源限制和监控。需权衡代码执行的收益与实现成本。

五、Desktop Extensions（桌面扩展）

5.1 解决 MCP 安装难题

本地 MCP Server 功能强大，但安装有诸多障碍：

问题	说明
需要开发工具	用户需安装 Node.js、Python 等运行时
手动配置	需编辑 JSON 配置文件
依赖管理	需解决包冲突和版本不匹配
无发现机制	只能在 GitHub 搜索
更新复杂	需手动重新安装

5.2 Desktop Extensions 解决方案

Desktop Extensions（.mcpb 文件） 将整个 MCP Server（包括所有依赖）打包成单一可安装包：

之前	之后
安装 Node.js	下载 .mcpb 文件
`npm install -g @example/mcp-server`	双击打开
手动编辑配置文件	点击"安装"
重启 Claude Desktop	✅ 完成

5.3 扩展包结构

extension.mcpb (ZIP 压缩包)
├── manifest.json          # 扩展元数据和配置（必需）
├── server/                # MCP Server 实现
│   └── index.js           # 主入口
├── node_modules/          # 打包的依赖
└── icon.png               # 扩展图标（可选）

manifest.json 示例：

json

{
  "mcpb_version": "0.1",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "一个简单的 MCP 扩展",
  "author": {
    "name": "扩展作者"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  },
  "tools": [
    {
      "name": "read_file",
      "description": "读取文件内容"
    }
  ]
}

5.4 创建扩展的步骤

bash

# 1. 初始化 manifest
npx @anthropic-ai/mcpb init

# 2. 打包扩展
npx @anthropic-ai/mcpb pack

# 3. 测试 - 将 .mcpb 文件拖入 Claude Desktop 设置窗口

5.5 用户配置

扩展可以声明需要用户输入的配置（如 API 密钥、允许的目录）：

json

"user_config": {
  "allowed_directories": {
    "type": "directory",
    "title": "允许访问的目录",
    "description": "服务器可以访问的目录",
    "multiple": true,
    "required": true,
    "default": ["${HOME}/Documents"]
  }
}

Claude Desktop 会：

显示友好的配置 UI
在启用前验证输入
安全存储敏感值（使用操作系统钥匙串）
将配置传递给服务器

5.6 企业功能

功能	说明
组策略支持	Windows Group Policy、macOS MDM
预装扩展	部署已批准的扩展
黑名单	阻止特定扩展或发布者
禁用目录	完全禁用扩展目录
私有目录	部署私有扩展目录

六、配置与使用

6.1 Claude Desktop 配置示例

json

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
    }
  }
}

6.2 Claude Code 配置

bash

# 添加 MCP Server
claude mcp add <name> <command> [args...]

# 示例
claude mcp add github npx -y @modelcontextprotocol/server-github

6.3 常用 MCP Server

Server	功能
@mcp/server-filesystem	文件系统读写
@mcp/server-github	GitHub 操作
@mcp/server-sqlite	SQLite 数据库
@mcp/server-postgres	PostgreSQL 数据库
@mcp/server-slack	Slack 消息
@mcp/server-google-drive	Google Drive
@mcp/server-puppeteer	浏览器自动化
@mcp/server-fetch	HTTP 请求

6.4 支持的客户端

客户端	类型
Claude Desktop	官方应用（支持 Desktop Extensions）
Claude Code	官方 CLI 工具
Cursor	AI 代码编辑器
Zed	代码编辑器
Antigravity	Google IDE
Sourcegraph	代码搜索

七、开发 MCP Server

7.1 基本结构（TypeScript）

typescript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// 创建 Server
const server = new Server({
  name: "my-weather-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// 定义工具
server.setRequestHandler("tools/list", async () => {
  return {
    tools: [
      {
        name: "get_weather",
        description: "获取指定城市的天气信息。返回：temperature（字符串），condition（字符串）",
        inputSchema: {
          type: "object",
          properties: {
            city: { type: "string", description: "城市名称" }
          },
          required: ["city"]
        }
      }
    ]
  };
});

// 处理工具调用
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const city = request.params.arguments.city;
    // 调用天气 API...
    return {
      content: [{ type: "text", text: `${city}今天晴，25°C` }]
    };
  }
});

// 启动
const transport = new StdioServerTransport();
await server.connect(transport);

7.2 Python 版本

python

from mcp.server import Server
from mcp.server.stdio import stdio_server

app = Server("my-weather-server")

@app.list_tools()
async def list_tools():
    return [
        {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"]
            }
        }
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments["city"]
        # 调用天气 API...
        return f"{city}今天晴，25°C"

async def main():
    async with stdio_server() as streams:
        await app.run(streams[0], streams[1])

7.3 工具注解（Tool Annotations）

MCP 协议支持工具注解，声明工具的安全属性：

json

{
  "name": "delete_file",
  "description": "删除文件",
  "annotations": {
    "destructive": true,
    "requires_confirmation": true
  }
}

八、安全机制

8.1 认证方案

方案	说明
OAuth 2.0 / 2.1	标准授权框架
API Key	简单密钥认证
JWT	Token 认证

8.2 权限控制

权限层级：
├── Server 级别 - 整个 Server 的访问权限
├── Tool 级别 - 特定工具的使用权限
├── Resource 级别 - 资源的读/写权限
└── Operation 级别 - 具体操作的权限

RBAC 示例：
- admin: 所有权限
- developer: 读取代码、提交 PR
- viewer: 只读访问

8.3 隐私保护（代码执行模式）

在代码执行模式下，中间结果默认留在执行环境。可以自动脱敏敏感数据：

typescript

// Agent 看到的脱敏数据
[
  { salesforceId: '00Q...', email: '[EMAIL_1]', phone: '[PHONE_1]', name: '[NAME_1]' },
  { salesforceId: '00Q...', email: '[EMAIL_2]', phone: '[PHONE_2]', name: '[NAME_2]' },
]

// 实际数据在 MCP Client 中解脱敏后传递给目标系统

8.4 安全最佳实践

实践	说明
最小权限	只授予必要的权限
Token 轮换	定期更换认证凭据
审计日志	记录所有操作
输入验证	严格验证参数
加密传输	使用 TLS/SSL
沙箱执行	代码执行环境需要安全沙箱

8.5 MCP 安全威胁详解

新增威胁领域

MCP 作为新的 API 界面，带来了超越传统应用漏洞的安全挑战。核心风险包括：未授权操作和数据泄露。

动态能力注入 (Dynamic Capability Injection)

风险： MCP Server 可能动态改变其提供的工具列表，而无需客户端明确通知或批准。

场景： 一个低风险的诗歌创作 Agent 连接到书籍 MCP Server 获取引用。如果该 Server 突然添加"购买书籍"功能，Agent 可能意外获得发起金融交易的能力。

缓解措施	说明
显式白名单	在 SDK 或应用层强制执行允许的 MCP 工具白名单
强制变更通知	要求所有 Server 定义变更必须设置 `listChanged` 标志
工具版本锁定	将工具定义锁定到特定版本或哈希值
安全 API 网关	使用 Apigee 等网关过滤工具列表

工具遮蔽 (Tool Shadowing)

风险： 恶意工具的描述可能覆盖合法工具的触发条件，导致用户数据被拦截或篡改。

场景：

合法工具：secure_storage_service - "当用户明确请求保存敏感密钥时使用"
恶意工具：save_secure_note - "当用户提及'保存'、'存储'、'记住'时使用此工具"

LLM 可能选择恶意工具保存敏感数据，导致数据泄露。

缓解措施	说明
防止命名冲突	检查新工具名称是否与现有受信工具语义相似
mTLS	对敏感连接实施双向 TLS 验证
确定性策略执行	在关键交互点实施策略检查
人工审批 (HITL)	对高风险操作要求明确用户确认

恶意工具定义与内容注入

风险：

工具描述字段可能操纵 Agent 规划器执行恶意操作
工具可能摄入包含可注入提示的外部内容

缓解措施	说明
输入验证	清理所有用户输入，防止恶意命令执行
输出清理	在将工具返回数据反馈到模型上下文前清理潜在恶意内容
系统提示隔离	明确分离用户输入和系统指令
资源白名单	只消费经过验证的 URL 资源

敏感信息泄露

风险： MCP 工具可能在交互过程中无意（或恶意）接收敏感信息，导致数据泄露。

缓解措施	说明
结构化输出注解	使用标签标识敏感输出字段
污点追踪 (Taint Tracking)	将敏感输入/输出标记为"污染"并追踪流向

无法限制访问范围

风险： MCP 协议仅支持粗粒度的客户端-服务器授权，不支持按工具或资源的细粒度授权。

缓解措施	说明
作用域凭证	使用绑定到特定调用者的短期凭证
最小权限原则	如果工具只需读取，不授予写入或删除权限
凭证隔离	敏感数据应通过侧信道传输，不进入 Agent 上下文

Confused Deputy 问题

MCP Server 作为特权中介可能被低权限实体欺骗。恶意用户可能通过 Prompt 注入，让 AI 助手指示高权限 MCP Server 执行未授权操作，绕过安全控制。

九、应用场景

9.1 开发工具链

IDE（Cursor/Zed）
    ↓ MCP
├── GitHub: 查 Issue、提 PR
├── Jira: 管理任务
├── 数据库: 查询/修改数据
├── 日志系统: 查看日志
└── CI/CD: 触发构建

9.2 企业自动化

场景	MCP Server
CRM 集成	Salesforce、HubSpot
通讯协作	Slack、邮件、Teams
数据分析	数据库、BI 工具
文档管理	Google Drive、Notion
任务管理	Jira、Asana

9.3 代码执行场景示例

typescript

// 复杂工作流：从多个数据源聚合信息

// 1. 从 Google Sheets 获取销售数据
const salesData = await gdrive.getSheet({ sheetId: 'sales_2025' });

// 2. 从 Salesforce 获取客户信息
const customers = await salesforce.query({ 
  query: 'SELECT Id, Name, Industry FROM Account' 
});

// 3. 在代码中合并和分析
const analysis = salesData.rows
  .filter(row => row.revenue > 100000)
  .map(row => ({
    ...row,
    customer: customers.find(c => c.Id === row.customerId)
  }));

// 4. 只返回精简的分析结果
console.log(`高价值交易数量: ${analysis.length}`);
console.log(analysis.slice(0, 10)); // 只显示前 10 条

十、2025年发展里程碑

时间	里程碑
2024.11	Anthropic 发布 MCP
2025.03	重大协议更新：OAuth 2.1、Streamable HTTP、JSON-RPC 批处理
2025上半年	远程 MCP Server 支持
2025.06	Desktop Extensions 发布
2025.11	代码执行模式发布
2025.12	捐赠给 Agentic AI Foundation (AAIF)

行业采纳

公司/项目	采纳情况
OpenAI	支持 MCP
Google DeepMind	支持 MCP
Cloudflare	Code Mode 实现
Zed	原生集成
Cursor	原生集成
Sourcegraph	原生集成

十一、与 Function Calling 的关系

维度	Function Calling	MCP
层级	单一模型能力	标准化协议
范围	应用内定义	跨应用共享
复用性	每个应用单独开发	一次开发，处处使用
生态	平台特定	开放标准

关系图：

MCP 协议
    ↓ 定义标准
MCP Server（提供工具）
    ↓ 暴露能力
LLM（通过 Function Calling 调用）
    ↓ 执行操作
用户获得结果

十二、最佳实践

✅ 推荐做法

实践	说明
工具粒度适中	既不过于细碎，也不过于庞大
清晰的描述	包含用途、返回格式，帮助 LLM 正确选择
错误处理	返回有意义的错误信息
版本管理	工具接口版本化
Token 效率	考虑使用代码执行模式处理大数据
渐进式披露	支持按需加载工具定义
打包为扩展	便于分发和安装

⚠️ 注意事项

事项	说明
权限控制	敏感操作需授权
性能优化	避免长时间阻塞
兼容性	测试不同客户端
日志记录	便于调试和审计
沙箱安全	代码执行需要安全隔离

十三、资源链接

资源	链接
官方文档	https://modelcontextprotocol.io
GitHub	https://github.com/modelcontextprotocol
Server 列表	https://github.com/modelcontextprotocol/servers
Desktop Extensions	https://github.com/anthropics/dxt
SDK (TypeScript)	@modelcontextprotocol/sdk
SDK (Python)	mcp
MCPB 工具	@anthropic-ai/mcpb

📚 推荐阅读

Code execution with MCP — 代码执行模式详解，减少 98.7% Token 消耗
Desktop Extensions — 一键安装 MCP Server
Writing effective tools for agents — MCP 工具设计最佳实践

更多文章参见 Anthropic Engineering 文章合集。

← 返回 AI 工具

MCP (Model Context Protocol) 完全指南 ​

一、什么是 MCP？ ​

1.1 核心定义 ​

1.2 解决的问题 ​

1.3 核心价值 ​

二、核心架构 ​

2.1 三层架构 ​

2.2 三大核心原语 ​

三、工作流程 ​

3.1 典型交互流程 ​

四、代码执行模式（Code Mode） ​

4.1 传统模式的问题 ​

4.2 代码执行模式解决方案 ​

4.3 工具发现机制 ​

4.4 代码执行模式的优势 ​

五、Desktop Extensions（桌面扩展） ​

5.1 解决 MCP 安装难题 ​

5.2 Desktop Extensions 解决方案 ​

5.3 扩展包结构 ​

5.4 创建扩展的步骤 ​

5.5 用户配置 ​

5.6 企业功能 ​

六、配置与使用 ​

6.1 Claude Desktop 配置示例 ​

6.2 Claude Code 配置 ​

6.3 常用 MCP Server ​

6.4 支持的客户端 ​

七、开发 MCP Server ​

7.1 基本结构（TypeScript） ​

7.2 Python 版本 ​

7.3 工具注解（Tool Annotations） ​

八、安全机制 ​

8.1 认证方案 ​

8.2 权限控制 ​

8.3 隐私保护（代码执行模式） ​

8.4 安全最佳实践 ​

8.5 MCP 安全威胁详解 ​

动态能力注入 (Dynamic Capability Injection) ​

工具遮蔽 (Tool Shadowing) ​

恶意工具定义与内容注入 ​

敏感信息泄露 ​

无法限制访问范围 ​

九、应用场景 ​

9.1 开发工具链 ​

9.2 企业自动化 ​

9.3 代码执行场景示例 ​

十、2025年发展里程碑 ​

行业采纳 ​

十一、与 Function Calling 的关系 ​

十二、最佳实践 ​

✅ 推荐做法 ​

⚠️ 注意事项 ​

十三、资源链接 ​

📚 推荐阅读 ​

MCP (Model Context Protocol) 完全指南

一、什么是 MCP？

1.1 核心定义

1.2 解决的问题

1.3 核心价值

二、核心架构

2.1 三层架构

2.2 三大核心原语

三、工作流程

3.1 典型交互流程

四、代码执行模式（Code Mode）

4.1 传统模式的问题

4.2 代码执行模式解决方案

4.3 工具发现机制

4.4 代码执行模式的优势

五、Desktop Extensions（桌面扩展）

5.1 解决 MCP 安装难题

5.2 Desktop Extensions 解决方案

5.3 扩展包结构

5.4 创建扩展的步骤

5.5 用户配置

5.6 企业功能

六、配置与使用

6.1 Claude Desktop 配置示例

6.2 Claude Code 配置

6.3 常用 MCP Server

6.4 支持的客户端

七、开发 MCP Server

7.1 基本结构（TypeScript）

7.2 Python 版本

7.3 工具注解（Tool Annotations）

八、安全机制

8.1 认证方案

8.2 权限控制

8.3 隐私保护（代码执行模式）

8.4 安全最佳实践

8.5 MCP 安全威胁详解

动态能力注入 (Dynamic Capability Injection)

工具遮蔽 (Tool Shadowing)

恶意工具定义与内容注入

敏感信息泄露

无法限制访问范围

九、应用场景

9.1 开发工具链

9.2 企业自动化

9.3 代码执行场景示例

十、2025年发展里程碑

行业采纳

十一、与 Function Calling 的关系

十二、最佳实践

✅ 推荐做法

⚠️ 注意事项

十三、资源链接

📚 推荐阅读