> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 模型上下文协议

> MCP模型上下文协议完整指南，介绍AI应用连接外部工具与数据的开源标准。涵盖Host/Client/Server三层架构、JSON-RPC通信机制、TypeScript与Python开发实践，以及安全认证与电商场景应用，帮助开发者快速掌握MCP协议核心知识体系

# MCP — 模型上下文协议

> "A USB-C port for AI applications."

## 什么是MCP

MCP（Model Context Protocol，模型上下文协议）是连接AI应用与外部系统的开源标准协议。它由Anthropic发起，设计灵感源自微软的Language Server Protocol (LSP)。MCP的设计哲学与LSP一致：通过标准化的协议层，将N x M的集成问题简化为N + M。

**官方规范**: [modelcontextprotocol.io](https://modelcontextprotocol.io)

**规范仓库**: [github.com/modelcontextprotocol/specification](https://github.com/modelcontextprotocol/specification)

**当前协议版本**: `2025-11-25`

**通俗解释**: USB-C让你的手机连接充电器、显示器、U盘。MCP让AI应用连接数据库、API、文件系统和各种工具。一个标准接口，连接一切。

## 广泛的生态支持

MCP已被以下AI应用和开发工具支持：

| 平台                      | 角色    | 说明              |
| ----------------------- | ----- | --------------- |
| **Claude** (Anthropic)  | AI助手  | 原生支持MCP连接器      |
| **ChatGPT** (OpenAI)    | AI助手  | 支持MCP服务器连接      |
| **VS Code** (Microsoft) | 开发工具  | Copilot支持MCP服务器 |
| **Cursor**              | 开发工具  | 原生MCP支持         |
| **Claude Code**         | CLI工具 | 原生MCP支持         |

## MCP架构

### 三个参与方

MCP是一个**有状态协议**，采用客户端-服务器架构，有三个核心参与方：

| 参与方            | 角色                        | 示例                               |
| -------------- | ------------------------- | -------------------------------- |
| **MCP Host**   | AI应用，管理一个或多个MCP客户端        | Claude Desktop, VS Code, ChatGPT |
| **MCP Client** | Host内部组件，与一个Server保持1:1连接 | Host内部自动创建                       |
| **MCP Server** | 提供工具、数据和提示词给客户端           | 你开发的服务                           |

### 两层架构

| 层       | 职责                                                | 协议与技术                           |
| ------- | ------------------------------------------------- | ------------------------------- |
| **数据层** | 定义消息结构和语义（生命周期、工具、资源、提示词、Sampling、Elicitation、日志） | JSON-RPC 2.0                    |
| **传输层** | 定义通信通道和认证                                         | stdio / Streamable HTTP / 自定义传输 |

### 传输方式

| 传输                  | 说明                                                | 适用场景            |
| ------------------- | ------------------------------------------------- | --------------- |
| **stdio**           | Server作为子进程，通过stdin/stdout通信，消息以换行符分隔             | 本地进程，无网络开销      |
| **Streamable HTTP** | 单一MCP端点，POST发送请求，GET订阅SSE流。`Mcp-Session-Id` 头管理会话 | 远程服务器，支持OAuth认证 |

## MCP的核心能力（Primitives）

### Server端 Primitives

**1. Tools（工具）** — 模型控制

AI模型自主决定何时调用的可执行函数。通过 `tools/list` 发现，通过 `tools/call` 执行。支持 `inputSchema` 定义输入参数，可选 `outputSchema` 定义结构化输出。

```json theme={null}
{
  "name": "weather_current",
  "description": "获取任意城市的当前天气",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "城市名" }
    },
    "required": ["location"]
  }
}
```

**2. Resources（资源）** — 应用控制

为AI应用提供上下文数据的数据源，通过URI标识（支持RFC 6570 URI模板）。通过 `resources/list` 发现，通过 `resources/read` 读取，支持 `resources/subscribe` 订阅变化。资源附带Annotations（audience、priority、lastModified等元数据）。

**3. Prompts（提示词）** — 用户控制

可复用的交互模板。通过 `prompts/list` 发现，通过 `prompts/get` 获取（支持arguments参数化）。

### Client端 Primitives

| Primitive       | 用途                     | 方法                              |
| --------------- | ---------------------- | ------------------------------- |
| **Sampling**    | Server请求Host的LLM完成一次推理 | `sampling/createMessage`        |
| **Roots**       | 告知Server文件系统边界         | `roots/list` (返回 `file://` URI) |
| **Elicitation** | Server请求用户提供信息         | `elicitation/request`           |

### 内容类型

MCP支持五种内容类型，均可携带Annotations：

| 类型                  | 说明             |
| ------------------- | -------------- |
| `text`              | 文本内容           |
| `image`             | 图片（Base64或URI） |
| `audio`             | 音频内容           |
| `resource_link`     | 资源链接引用         |
| `embedded_resource` | 嵌入式资源          |

## MCP在商务中的应用场景

| 场景       | MCP Server提供的工具                    | 效果                |
| -------- | ---------------------------------- | ----------------- |
| **商品搜索** | `search_products(query, category)` | AI代理可以搜索你的商品目录    |
| **库存查询** | `check_inventory(sku)`             | AI代理可以查询实时库存      |
| **订单状态** | `get_order_status(order_id)`       | 客户通过AI查询订单进度      |
| **退货处理** | `create_return(order_id, reason)`  | AI代理可以帮客户发起退货     |
| **价格查询** | `get_price(sku, quantity)`         | AI代理获取实时报价（含批量折扣） |
| **信任查询** | `otr_verify(domain)`               | AI代理查询商家信任评分      |

## MCP Server开发流程

### 1. 定义工具

确定你的MCP Server要暴露哪些工具。每个工具需要：

* 名称和描述（description直接影响AI模型的选择决策）
* 输入参数的JSON Schema（`inputSchema`）
* 可选的输出Schema（`outputSchema`，定义结构化返回格式）
* 执行逻辑

### 2. 选择SDK

MCP提供多语言SDK：

* **TypeScript/JavaScript**: `@modelcontextprotocol/sdk`
* **Python**: `mcp`
* **其他语言**: 通过JSON-RPC 2.0自行实现

### 3. 实现Server

```typescript theme={null}
// TypeScript MCP Server 示例框架
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "my-commerce-server",
  version: "1.0.0"
});

// 定义工具
server.tool(
  "search_products",
  "搜索商品",
  { query: { type: "string" }, category: { type: "string" } },
  async ({ query, category }) => {
    // 调用你的商品数据库或API
    const results = await searchProducts(query, category);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

// 启动
server.start();
```

### 4. 部署

* **本地Server**: 使用stdio传输，在用户机器上运行
* **远程Server**: 使用Streamable HTTP传输，部署在你的服务器上

### 5. 用户连接

用户在Claude/ChatGPT/VS Code等支持MCP的应用中添加你的Server连接信息即可使用。

## 协议生命周期

MCP连接有三个阶段：

```
1. 初始化（Initialization）
   → Client发送initialize请求，协商协议版本和能力
   → Server响应支持的能力
   → Client发送initialized通知确认

2. 操作（Operation）
   → Client请求tools/list获取可用工具列表
   → Client调用tools/call执行具体工具
   → Server推送工具列表变化等通知
   → Server可通过Sampling请求LLM推理
   → Server可通过Elicitation请求用户输入

3. 关闭（Shutdown）
   → 连接终止，清理资源
```

## 章节目录

1. [MCP核心概念](/zh/book-5/ch1-core-concepts) — 架构详解、参与方角色、协议生命周期
2. [数据层协议](/zh/book-5/ch2-data-layer) — JSON-RPC 2.0消息格式、能力协商
3. [传输层](/zh/book-5/ch3-transport) — stdio vs Streamable HTTP、OAuth 2.1认证
4. [构建MCP Server](/zh/book-5/ch4-build-server) — TypeScript/Python完整开发指南
5. [商务MCP Server](/zh/book-5/ch5-commerce-server) — 电商场景的MCP Server设计模式
6. [资源与提示词](/zh/book-5/ch6-resources-prompts) — Resources和Prompts的使用
7. [安全与认证](/zh/book-5/ch7-security) — OAuth 2.1集成、PKCE、权限管理
8. [测试与调试](/zh/book-5/ch8-testing) — MCP Inspector使用指南
9. [部署指南](/zh/book-5/ch9-deployment) — 本地部署vs远程部署
10. [实战案例](/zh/book-5/ch10-case-studies) — 不同场景的MCP Server实现

### AI提示词：构建商务MCP Server

```
请帮我构建一个商务场景的MCP Server。

准备工作：
1. 请阅读MCP官方文档：https://modelcontextprotocol.io
2. 特别阅读：/docs/develop/build-server

我的需求：
- 用途：【商品搜索/库存查询/订单管理/客服/其他】
- 技术栈：【TypeScript/Python/其他】
- 数据源：【数据库/API/文件】
- 部署方式：【本地/远程】

请输出：
1. MCP Server的工具设计（每个工具的名称、描述、输入输出）
2. 完整的可运行代码
3. 配置文件（Claude Desktop或其他客户端的连接配置）
4. 测试方法
5. 部署步骤
```

<Note>
  MCP是一个活跃发展的协议，规范持续更新中。本章内容基于截至2026年4月的官方文档（协议版本 `2025-11-25`）。请始终以 [modelcontextprotocol.io](https://modelcontextprotocol.io) 的最新版本为准。
</Note>