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

# 理解 MCP 客户端

MCP client 由 host 应用实例化，用来与特定 MCP server 通信。Claude.ai 或 IDE 这样的 host 应用负责管理整体用户体验，并协调多个 client。每个 client 负责与一个 server 的直接通信。

理解这个区别很重要：*host* 是用户实际交互的应用，而 *client* 是协议层组件，用于建立与 server 的连接。

## 核心客户端能力

除了使用 server 提供的上下文外，client 也可以向 server 提供若干能力。这些客户端能力让 server 作者可以构建更丰富的交互。

| 能力              | 说明                                                                                       | 示例                                           |
| --------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Elicitation** | Elicitation 让 server 可以在交互过程中向用户请求特定信息，为 server 按需收集信息提供结构化方式。                           | 旅行预订 server 可能询问用户的座位偏好、房型或联系电话，以完成预订。       |
| **Roots**       | Roots 允许 client 指定 server 应关注哪些目录，通过协调机制表达预期作用范围。                                        | 旅行预订 server 可能获得某个特定目录的访问范围，并从中读取用户日历。       |
| **Sampling**    | Sampling 允许 server 通过 client 请求 LLM 补全，从而支持 agentic workflow。这种方式让 client 完全控制用户权限和安全措施。 | 旅行预订 server 可能把航班列表发给 LLM，并请求 LLM 为用户选择最佳航班。 |

### Elicitation

Elicitation 让 server 可以在交互过程中向用户请求特定信息，从而创建更动态、更有响应性的工作流。

#### 概览

Elicitation 为 server 按需收集必要信息提供结构化方式。Server 不需要一开始就要求用户提供所有信息，也不必在缺少数据时失败；它可以暂停当前操作，向用户请求特定输入。这会形成更灵活的交互，让 server 能适应用户需求，而不是遵循僵硬流程。

**Elicitation 流程：**

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant Server

    Note over Server,Client: Server initiates elicitation
    Server->>Client: elicitation/create

    Note over Client,User: Human interaction
    Client->>User: Present elicitation UI
    User-->>Client: Provide requested information

    Note over Server,Client: Complete request
    Client-->>Server: Return user response

    Note over Server: Continue processing with new information
```

这个流程支持动态信息收集。Server 可以在需要时请求特定数据，用户通过合适的 UI 提供信息，server 再使用新获得的上下文继续处理。

**Elicitation 组件示例：**

```typescript theme={null}
{
  method: "elicitation/create",
  params: {
    message: "Please confirm your Barcelona vacation booking details:",
    schema: {
      type: "object",
      properties: {
        confirmBooking: {
          type: "boolean",
          description: "Confirm the booking (Flights + Hotel = $3,000)"
        },
        seatPreference: {
          type: "string",
          enum: ["window", "aisle", "no preference"],
          description: "Preferred seat type for flights"
        },
        roomType: {
          type: "string",
          enum: ["sea view", "city view", "garden view"],
          description: "Preferred room type at hotel"
        },
        travelInsurance: {
          type: "boolean",
          default: false,
          description: "Add travel insurance ($150)"
        }
      },
      required: ["confirmBooking"]
    }
  }
}
```

#### 示例：假期预订审批

旅行预订 server 可以通过最终预订确认流程展示 elicitation 的能力。当用户选择了理想的巴塞罗那度假套餐后，server 需要在继续之前收集最终审批和任何缺失信息。

Server 会使用结构化请求引出预订确认，其中包含行程摘要（6 月 15-22 日巴塞罗那航班、海滨酒店、总价 \$3,000），以及任何额外偏好的字段，例如座位选择、房型或旅行保险选项。

随着预订推进，server 会引出完成预订所需的联系信息。它可能要求提供航班预订的旅客详情、酒店特殊要求，或紧急联系人信息。

#### 用户交互模型

Elicitation 交互的设计目标是清晰、具备上下文，并尊重用户自主权：

**请求展示**：Client 会展示 elicitation 请求，并清楚说明是哪个 server 在请求、为什么需要这些信息，以及信息将如何使用。请求消息解释目的，schema 提供结构和校验。

**响应选项**：用户可以通过合适的 UI 控件（文本框、下拉框、复选框）提供请求的信息，也可以选择拒绝提供并附带说明，或取消整个操作。Client 会根据提供的 schema 校验响应，然后再返回给 server。

**隐私注意事项**：Elicitation 永远不应请求密码或 API key。Client 应对可疑请求发出警告，并让用户在发送前检查数据。

### Roots

Roots 定义 server 操作的文件系统边界，允许 client 指定 server 应关注哪些目录。

#### 概览

Roots 是 client 向 server 传达文件系统访问边界的机制。它们由 file URI 组成，用来表示 server 可以操作的目录，帮助 server 理解可用文件和文件夹的范围。虽然 roots 会传达预期边界，但它们并不强制执行安全限制。真正的安全性必须通过操作系统层面的文件权限和/或沙箱来强制保证。

**Root 结构：**

```json theme={null}
{
  "uri": "file:///Users/agent/travel-planning",
  "name": "Travel Planning Workspace"
}
```

Roots 只表示文件系统路径，并始终使用 `file://` URI scheme。它们帮助 server 理解项目边界、工作区组织和可访问目录。随着用户处理不同项目或文件夹，roots 列表可以动态更新；边界变化时，server 会通过 `roots/list_changed` 接收通知。

#### 示例：旅行规划工作区

处理多个客户行程的旅行顾问，可以用 roots 来组织文件系统访问。设想一个工作区中有多个目录，分别对应旅行规划的不同方面。

Client 向旅行规划 server 提供文件系统 roots：

* `file:///Users/agent/travel-planning` - 包含所有旅行文件的主工作区。
* `file:///Users/agent/travel-templates` - 可复用的行程模板和资源。
* `file:///Users/agent/client-documents` - 客户护照和旅行文件。

当 agent 创建巴塞罗那行程时，行为良好的 server 会尊重这些边界：在指定 roots 内访问模板、保存新行程，并引用客户文件。Server 通常会使用相对于 root 目录的路径访问 root 内文件，或使用尊重 root 边界的文件搜索工具。

如果 agent 打开类似 `file:///Users/agent/archive/2023-trips` 的归档文件夹，client 会通过 `roots/list_changed` 更新 roots 列表。

关于尊重 roots 的完整 server 实现，请参阅官方 servers 仓库中的 [filesystem server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)。

#### 设计理念

Roots 是 client 与 server 之间的协调机制，而不是安全边界。规范要求 server “SHOULD respect root boundaries”，而不是 “MUST enforce” 它们，因为 server 运行的是 client 无法控制的代码。

当 server 可信或已经过审查、用户理解 roots 的建议性质，并且目标是防止意外而不是阻止恶意行为时，roots 最有效。它们擅长上下文限定（告诉 server 应关注哪里）、防止误操作（帮助行为良好的 server 保持在边界内）和工作流组织（例如自动管理项目边界）。

#### 用户交互模型

Roots 通常由 host 应用根据用户行为自动管理，不过有些应用可能会暴露手动 root 管理：

**自动 root 检测**：当用户打开文件夹时，client 会自动将其暴露为 roots。打开旅行工作区后，client 可以把该目录作为 root 暴露出去，帮助 server 理解当前工作范围内有哪些行程和文档。

**手动 root 配置**：高级用户可以通过配置指定 roots。例如，添加 `/travel-templates` 作为可复用资源目录，同时排除包含财务记录的目录。

### Sampling

Sampling 允许 server 通过 client 请求语言模型补全，在保持安全和用户控制的同时支持 agentic 行为。

#### 概览

Sampling 让 server 可以执行依赖 AI 的任务，而不必直接集成 AI 模型或为模型付费。Server 可以请求已经具备 AI 模型访问能力的 client 代为处理这些任务。这种方式让 client 完全控制用户权限和安全措施。由于 sampling 请求发生在其他操作上下文中，例如某个 tool 正在分析数据，并且作为独立模型调用处理，因此它能在不同上下文之间保持清晰边界，更高效地使用上下文窗口。

**Sampling 流程：**

```mermaid theme={null}
sequenceDiagram
    participant LLM
    participant User
    participant Client
    participant Server

    Note over Server,Client: Server initiates sampling
    Server->>Client: sampling/createMessage

    Note over Client,User: Human-in-the-loop review
    Client->>User: Present request for approval
    User-->>Client: Review and approve/modify

    Note over Client,LLM: Model interaction
    Client->>LLM: Forward approved request
    LLM-->>Client: Return generation

    Note over Client,User: Response review
    Client->>User: Present response for approval
    User-->>Client: Review and approve/modify

    Note over Server,Client: Complete request
    Client-->>Server: Return approved response
```

这个流程通过多个人在环检查点确保安全。用户可以在响应返回 server 前，审查并修改初始请求和生成结果。

**请求参数示例：**

```typescript theme={null}
{
  messages: [
    {
      role: "user",
      content: "Analyze these flight options and recommend the best choice:\n" +
               "[47 flights with prices, times, airlines, and layovers]\n" +
               "User preferences: morning departure, max 1 layover"
    }
  ],
  modelPreferences: {
    hints: [{
      name: "claude-sonnet-4-20250514"  // Suggested model
    }],
    costPriority: 0.3,      // Less concerned about API cost
    speedPriority: 0.2,     // Can wait for thorough analysis
    intelligencePriority: 0.9  // Need complex trade-off evaluation
  },
  systemPrompt: "You are a travel expert helping users find the best flights based on their preferences",
  maxTokens: 1500
}
```

#### 示例：航班分析工具

设想一个旅行预订 server，其中有一个名为 `findBestFlight` 的 tool，它使用 sampling 分析可用航班并推荐最佳选择。当用户说“帮我预订下个月去巴塞罗那的最佳航班”时，这个 tool 需要 AI 协助评估复杂权衡。

该 tool 查询航空公司 API，收集 47 个航班选项。随后它请求 AI 协助分析这些选项：“Analyze these flight options and recommend the best choice: \[47 flights with prices, times, airlines, and layovers] User preferences: morning departure, max 1 layover.”

Client 发起 sampling 请求，让 AI 评估各种权衡，例如更便宜的红眼航班与更方便的早晨出发航班。该 tool 使用分析结果展示前三个推荐。

#### 用户交互模型

虽然不是强制要求，但 sampling 的设计允许人在环控制。用户可以通过多种机制保持监督：

**审批控制**：Sampling 请求可能需要用户明确同意。Client 可以展示 server 想分析什么以及为什么分析。用户可以批准、拒绝或修改请求。

**透明性功能**：Client 可以显示确切 prompt、模型选择和 token 限制，让用户在响应返回 server 之前审查 AI 响应。

**配置选项**：用户可以设置模型偏好，为可信操作配置自动批准，或要求所有请求都经过批准。Client 也可以提供选项来删改敏感信息。

**安全注意事项**：Client 和 server 都必须在 sampling 过程中妥善处理敏感数据。Client 应实现速率限制，并校验所有消息内容。人在环设计确保由 server 发起的 AI 交互不会在未经用户明确同意的情况下破坏安全性或访问敏感数据。