一、MCP Server 与 Client 的职责划分
MCP 的工程实现可以分为两个核心部分:
- MCP Server: 将外部业务能力封装为 MCP 标准接口。
- MCP Client: 连接 MCP Server,发现和调用其提供的能力。
两者通过 MCP 协议通信,底层使用 JSON-RPC 消息格式和标准传输机制。
1.1 MCP Server 的核心职责
MCP Server 是能力提供方,负责将业务系统转换为模型可以理解和调用的标准能力。
主要职责:
| 模块 | 职责 |
|---|---|
| 能力注册 | 注册 Tools、Resources、Prompts |
| 参数定义 | 声明输入参数及数据结构 |
| 参数校验 | 验证请求参数的类型和约束 |
| 请求处理 | 接收并路由 MCP 请求 |
| 业务执行 | 调用数据库、API、文件系统等 |
| 结果封装 | 将业务结果转换为 MCP 响应 |
| 权限控制 | 校验身份、授权范围和操作权限 |
| 异常处理 | 处理协议错误和业务错误 |
Server 并不需要理解大模型的内部推理过程。它只需要提供清晰、可靠、可调用的能力接口。
1.2 MCP Client 的核心职责
MCP Client 是能力调用方,通常运行在 Host 内部。
主要职责:
| 模块 | 职责 |
|---|---|
| 连接管理 | 建立和关闭 Server 连接 |
| 传输管理 | 管理 STDIO 或 Streamable HTTP |
| 协议处理 | 发送和解析 JSON-RPC 消息 |
| 能力发现 | 获取 Server 提供的工具、资源和提示 |
| 工具调用 | 根据工具名称和参数发起调用 |
| 请求管理 | 管理请求 ID、超时和并发 |
| 结果处理 | 解析工具返回内容 |
| 异常处理 | 处理连接失败、协议错误和业务错误 |
Client 不直接执行 Server 内部的业务逻辑,而是通过协议请求 Server 完成操作。
1.3 两者的完整协作关系
flowchart TB
A["用户请求"] --> B["Host"]
B --> C["LLM"]
B --> D["MCP Client"]
D --> E["建立传输连接"]
E --> F["MCP Server"]
F --> G["能力注册表"]
F --> H["业务处理层"]
H --> I["Database / API / File System"]
D --> J["发现 Tools"]
J --> G
D --> K["调用 Tool"]
K --> F
F --> H
H --> L["返回执行结果"]
L --> D
D --> B
B --> C
style A fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style B fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F
这里需要区分两个层次:
协议调用与模型决策不是同一件事。
MCP Client 可以直接调用工具,并不要求每次调用都经过大模型。模型负责决定何时使用工具,Host 负责协调模型和 MCP Client,Client 负责执行协议调用。
二、MCP Server 的内部架构
一个可维护的 MCP Server 不应该只是若干个工具处理函数的集合,而应该具有清晰的分层结构。
2.1 推荐架构
flowchart TB
A["MCP Client"] --> B["Transport Layer"]
B --> C["Protocol Handler"]
C --> D["Method Router"]
D --> E["Tools Registry"]
D --> F["Resources Registry"]
D --> G["Prompts Registry"]
E --> H["Tool Handler"]
F --> I["Resource Handler"]
G --> J["Prompt Handler"]
H --> K["Application Service"]
I --> K
J --> K
K --> L["Repository / Adapter"]
L --> M["Database / External API / File System"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style K fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style L fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style M fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
各层的职责:
- Transport Layer:处理 STDIO 或 HTTP 消息传输。
- Protocol Handler:解析 JSON-RPC 消息并处理协议语义。
- Method Router:根据 MCP 方法分发请求。
- Registry:维护已注册的工具、资源和提示。
- Handler:执行对应能力的处理逻辑。
- Application Service:实现业务规则。
- Repository / Adapter:访问底层系统。
SDK 通常已经封装了传输、协议解析和方法路由,因此开发者主要实现能力注册、业务处理和安全控制。
2.2 Server 的核心对象
以 TypeScript SDK v2 为例,服务端使用 McpServer 创建协议服务实例。
核心概念:
| 对象 | 作用 |
|---|---|
McpServer |
管理 Server 能力与协议接口 |
| Tool | 注册可执行工具 |
| Resource | 注册可读取资源 |
| Prompt | 注册提示模板 |
| Transport | 提供底层通信通道 |
| Handler | 实际处理业务请求 |
Server 的生命周期由应用程序负责启动和关闭,传输对象负责承载协议消息。
2.3 创建项目
当前 TypeScript SDK v2 使用独立的 Server 和 Client 包。
mkdir mcp-demo
cd mcp-demo
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript tsx @types/node
npx tsc --init
建议项目结构:
mcp-demo/
├── src/
│ ├── server/
│ │ ├── index.ts
│ │ ├── tools.ts
│ │ ├── resources.ts
│ │ └── prompts.ts
│ ├── services/
│ │ └── user-service.ts
│ ├── repositories/
│ │ └── user-repository.ts
│ └── shared/
│ └── types.ts
├── package.json
└── tsconfig.json
这里将 MCP 协议层与业务服务层分开,避免工具处理函数直接承担所有业务逻辑。
三、MCP Server:实现工具注册与调用
Tools 是 MCP Server 最常见的能力类型。
它允许 Client 发现工具的名称、描述和输入结构,并通过 tools/call 请求执行。
3.1 定义一个 Tool
以用户查询工具为例。
import * as z from "zod/v4";
const inputSchema = {
userId: z.string().min(1).describe("用户 ID"),
};
async function getUser(userId: string) {
return {
id: userId,
name: "Alice",
email: "alice@example.com",
};
}
工具需要具备三个核心要素:
- 名称:用于调用时定位工具。
- 描述:帮助模型和客户端理解工具用途。
- 输入 Schema:定义调用参数的结构和约束。
工具描述不应该只写一个名称。对于模型而言,描述质量直接影响工具选择和参数构造的准确性。
3.2 注册 Tool
import { McpServer } from "@modelcontextprotocol/server";
import * as z from "zod/v4";
const server = new McpServer({
name: "user-service",
version: "1.0.0",
});
server.registerTool(
"get_user",
{
title: "查询用户",
description: "根据用户 ID 查询用户基本信息",
inputSchema: {
userId: z.string().min(1),
},
},
async ({ userId }) => {
const user = await getUser(userId);
return {
content: [
{
type: "text",
text: JSON.stringify(user),
},
],
};
},
);
registerTool 将工具元数据、输入 Schema 和执行处理函数绑定在一起。
当 Client 调用 tools/list 时,SDK 可以根据注册信息生成工具描述。
当 Client 调用 tools/call 时,SDK 根据工具名称找到对应处理函数。
3.3 工具参数校验
参数校验是 Server 实现中非常重要的一环。
不能因为 Client 声明了参数 Schema,就假设所有请求一定合法。
原因包括:
- Client 可能存在实现缺陷。
- 参数可能由模型生成。
- 用户可能构造恶意请求。
- 旧版本 Client 可能发送不兼容参数。
- 网络请求可能被人为修改。
例如:
const searchSchema = {
keyword: z.string().min(1).max(100),
limit: z.number().int().min(1).max(50).default(10),
};
这里包含:
- 类型约束。
- 非空约束。
- 字符长度限制。
- 整数约束。
- 数值范围限制。
- 默认值。
参数 Schema 既是协议接口描述,也是服务端输入校验的重要依据。
但 Schema 校验不能代替业务权限校验。例如,userId 即使是合法字符串,也不代表当前用户有权读取该用户的数据。
3.4 Tool 的返回结果
MCP 工具通常通过 content 返回内容。
例如:
return {
content: [
{
type: "text",
text: "查询成功",
},
],
};
也可以返回结构化数据:
return {
content: [
{
type: "text",
text: "查询成功",
},
],
structuredContent: {
id: "1001",
name: "Alice",
active: true,
},
};
两者用途不同:
content:面向通用内容展示和处理。structuredContent:提供结构化结果,便于客户端程序直接消费。
如果工具定义了输出 Schema,应确保实际返回的数据符合该结构。
不要将所有结果都简单地 JSON 序列化为文本。对于需要程序化处理的数据,结构化输出更合适。
3.5 完整 Server 示例
下面实现一个可通过 STDIO 启动的用户服务 MCP Server。
// src/server/index.ts
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
const users = [
{
id: "1001",
name: "Alice",
email: "alice@example.com",
},
{
id: "1002",
name: "Bob",
email: "bob@example.com",
},
];
const server = new McpServer({
name: "user-service",
version: "1.0.0",
});
// 注册查询用户工具
server.registerTool(
"get_user",
{
title: "查询用户",
description: "根据用户 ID 查询用户信息",
inputSchema: {
userId: z.string().min(1),
},
},
async ({ userId }) => {
const user = users.find((item) => item.id === userId);
if (!user) {
return {
content: [
{
type: "text",
text: `用户不存在:${userId}`,
},
],
isError: true,
};
}
return {
content: [
{
type: "text",
text: JSON.stringify(user),
},
],
structuredContent: user,
};
},
);
// 注册用户列表工具
server.registerTool(
"list_users",
{
title: "用户列表",
description: "查询系统中的用户列表",
inputSchema: {
keyword: z.string().optional(),
},
},
async ({ keyword }) => {
const result = users.filter((user) => {
if (!keyword) return true;
return (
user.name.includes(keyword) ||
user.email.includes(keyword)
);
});
return {
content: [
{
type: "text",
text: JSON.stringify(result),
},
],
structuredContent: {
users: result,
total: result.length,
},
};
},
);
// 启动 STDIO Server
serveStdio(() => server);
启动:
npx tsx src/server/index.ts
这个 Server 会通过标准输入输出与 MCP Client 通信。
注意:实际 STDIO Server 的 stdout 只能用于 MCP 协议消息,调试日志应输出到 stderr,不能使用普通 console.log 污染协议通道。
四、MCP Server:实现 Resources 与 Prompts
除了 Tools,Server 还可以提供 Resources 和 Prompts。
三者的设计目标不同,不能简单地都当作工具处理。
4.1 Resources:提供数据资源
Resources 主要用于暴露可读取的数据。
例如:
- 配置文件。
- 项目文档。
- 数据库中的只读信息。
- API 返回的数据。
- 系统运行状态。
注册资源:
server.registerResource(
"project-config",
"config://project",
{
title: "项目配置",
description: "读取当前项目的配置文件",
mimeType: "application/json",
},
async (uri) => {
const config = {
name: "mcp-demo",
version: "1.0.0",
environment: "development",
};
return {
contents: [
{
uri: uri.href,
mimeType: "application/json",
text: JSON.stringify(config),
},
],
};
},
);
Resource 的关键在于 URI。
Client 可以根据 URI 读取指定资源,而不必知道资源背后的数据库或文件系统实现。
4.2 Resource Template:参数化资源
有些资源不是固定地址,而是根据参数动态定位。
例如:
user://1001
user://1002
user://1003
这类场景可以使用 Resource Template。
server.registerResource(
"user-profile",
"user://{userId}",
{
title: "用户资料",
description: "根据用户 ID 读取用户资料",
mimeType: "application/json",
},
async (uri, { userId }) => {
const user = users.find(
(item) => item.id === userId,
);
if (!user) {
throw new Error("User not found");
}
return {
contents: [
{
uri: uri.href,
mimeType: "application/json",
text: JSON.stringify(user),
},
],
};
},
);
Resource Template 适合参数化资源访问,但它仍然是资源读取机制,不等同于可执行 Tool。
4.3 Prompts:提供可复用提示模板
Prompts 用于向 Client 暴露可复用的提示模板。
例如代码审查模板:
server.registerPrompt(
"review_code",
{
title: "代码审查",
description: "根据指定语言审查代码",
argsSchema: {
language: z.string(),
code: z.string(),
},
},
async ({ language, code }) => {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `
请审查以下 ${language} 代码。
重点检查:
1. 逻辑错误
2. 性能问题
3. 安全风险
4. 可维护性
代码:
${code}
`,
},
},
],
};
},
);
Prompts 的重点是提示模板管理,而不是执行外部业务操作。
4.4 三种能力的选择
| 能力 | 主要用途 | 是否执行操作 |
|---|---|---|
| Tools | 执行业务动作或计算 | 可以 |
| Resources | 暴露可读取的数据 | 主要用于读取 |
| Prompts | 提供可复用提示模板 | 不负责业务执行 |
选择时可以遵循:
- 需要执行查询、创建、修改或计算,优先考虑 Tool。
- 需要提供可读取的数据,考虑 Resource。
- 需要提供标准化的提示模板,考虑 Prompt。
实际应用中三者可以组合使用。
五、MCP Server:业务逻辑与异常处理
工具注册只是入口,真正的工程难点在于业务逻辑的可靠执行。
5.1 不要将业务逻辑写在 Tool Handler 中
不推荐:
server.registerTool(
"create_order",
{
description: "创建订单",
inputSchema: {
productId: z.string(),
quantity: z.number(),
},
},
async ({ productId, quantity }) => {
// 参数校验
// 用户权限判断
// 库存查询
// 价格计算
// 数据库事务
// 订单创建
// 日志记录
// 返回结果
},
);
这种写法会导致协议处理和业务逻辑高度耦合。
更合理的方式是分层:
server.registerTool(
"create_order",
{
description: "创建订单",
inputSchema: {
productId: z.string(),
quantity: z.number().int().min(1),
},
},
async ({ productId, quantity }) => {
const result = await orderService.createOrder({
productId,
quantity,
});
return {
content: [
{
type: "text",
text: JSON.stringify(result),
},
],
structuredContent: result,
};
},
);
业务规则放在 orderService,数据访问放在 Repository。
这样同一套业务逻辑可以被 MCP Server、REST API 和后台任务复用。
5.2 业务错误与协议错误
MCP Server 需要区分两类失败。
协议错误:
- JSON-RPC 格式不正确。
- 方法不存在。
- 参数结构无效。
- 请求不符合协议要求。
这类错误由 SDK 的协议层负责处理。
工具执行错误:
- 用户不存在。
- 库存不足。
- 数据库不可用。
- 外部 API 请求失败。
- 当前用户没有执行权限。
工具业务错误可以通过工具结果的 isError 表达。
例如:
server.registerTool(
"get_user",
{
description: "查询用户",
inputSchema: {
userId: z.string(),
},
},
async ({ userId }) => {
try {
const user = await userService.getUser(userId);
return {
content: [
{
type: "text",
text: JSON.stringify(user),
},
],
structuredContent: user,
};
} catch (error) {
console.error("get_user failed:", error);
return {
content: [
{
type: "text",
text: "查询用户失败,请检查用户 ID 或稍后重试",
},
],
isError: true,
};
}
},
);
生产环境中不应把数据库连接字符串、SQL 堆栈、内部文件路径或访问令牌直接返回给模型。
5.3 幂等性与副作用控制
对于只读工具,重复调用通常不会造成数据修改。
但对于以下操作:
- 创建订单。
- 扣减库存。
- 转账。
- 删除文件。
- 修改用户权限。
重复执行可能产生严重后果。
因此,具有副作用的工具应考虑:
- 幂等键。
- 操作记录。
- 数据库事务。
- 状态校验。
- 重复请求检测。
- 高风险操作的用户确认。
MCP 的请求 ID 只是协议层请求关联标识,不能直接当作业务幂等键。
同一个业务动作可能经过不同请求 ID 重试,因此需要独立设计业务幂等机制。
六、MCP Server:STDIO 与 Streamable HTTP 实现
Server 的业务能力可以保持一致,传输层则根据部署场景选择。
6.1 STDIO Server
STDIO 适合本地工具集成。
例如:
- 本地文件系统。
- 本地代码仓库。
- 开发环境工具。
- 桌面 AI 应用。
使用官方 TypeScript SDK v2:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
const server = new McpServer({
name: "local-tools",
version: "1.0.0",
});
server.registerTool(
"hello",
{
description: "返回问候信息",
inputSchema: {},
},
async () => ({
content: [
{
type: "text",
text: "Hello MCP",
},
],
}),
);
serveStdio(() => server);
Host 启动 Server 子进程后,Client 通过子进程的标准输入输出与其通信。
6.2 Streamable HTTP Server
远程部署通常使用 Streamable HTTP。
import { McpServer } from "@modelcontextprotocol/server";
import { serve } from "@modelcontextprotocol/server/http";
const server = new McpServer({
name: "remote-tools",
version: "1.0.0",
});
server.registerTool(
"get_status",
{
description: "获取系统运行状态",
inputSchema: {},
},
async () => ({
content: [
{
type: "text",
text: JSON.stringify({
status: "healthy",
timestamp: new Date().toISOString(),
}),
},
],
}),
);
serve(server, {
port: 3000,
});
这里展示的是 SDK v2 的 HTTP 启动模式。实际部署时还需要根据所使用的 SDK 版本和运行环境配置认证、监听地址、请求限制和关闭流程。
6.3 传输层如何选择
| 场景 | 推荐传输 |
|---|---|
| 本地桌面应用 | STDIO |
| 本地开发工具 | STDIO |
| 本地子进程集成 | STDIO |
| 远程企业服务 | Streamable HTTP |
| 多实例部署 | Streamable HTTP |
| 云端 MCP 服务 | Streamable HTTP |
业务能力不应与传输实现耦合。
同一个 Server 可以通过不同 Transport 对外提供相同的业务接口,但应根据 SDK 的具体接口和部署方式配置相应的传输适配。
七、MCP Client 的内部架构
MCP Client 负责连接 Server 并使用其提供的能力。
它通常包括以下模块:
| 模块 | 职责 |
|---|---|
| Client Instance | MCP 客户端实例 |
| Transport | 传输连接 |
| Protocol Layer | JSON-RPC 消息管理 |
| Discovery | 能力发现 |
| Tool Manager | 工具列表和调用 |
| Resource Manager | 资源列表和读取 |
| Prompt Manager | 提示模板列表和获取 |
| Request Manager | 请求关联、超时和并发 |
| Result Adapter | 结果转换 |
7.1 Client 的工作流程
flowchart TD
A["创建 MCP Client"] --> B["创建 Transport"]
B --> C["连接 MCP Server"]
C --> D["确定协议版本"]
D --> E["发现 Server 能力"]
E --> F["获取 Tools / Resources / Prompts"]
F --> G["保存可用能力"]
G --> H["等待调用请求"]
H --> I["构造 MCP 请求"]
I --> J["发送请求"]
J --> K["接收响应"]
K --> L["解析执行结果"]
L --> M["返回 Host"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#EAF3EC,stroke:#83A995,color:#315D49
style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style J fill:#EAF3EC,stroke:#83A995,color:#315D49
style K fill:#EAF3EC,stroke:#83A995,color:#315D49
style L fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F
注意:能力发现与连接建立的具体顺序取决于协议版本和 SDK。旧版协议需要先完成初始化握手;新版无状态协议可以在需要时进行能力发现,再发送独立请求。
7.2 创建 Client
TypeScript SDK v2 将 Client 与 Server 拆分为独立包。
安装:
npm install @modelcontextprotocol/client
创建客户端:
import { Client } from "@modelcontextprotocol/client";
const client = new Client({
name: "demo-client",
version: "1.0.0",
});
Client 负责 MCP 协议层面的能力调用,不负责决定大模型是否应该使用某个工具。
7.3 连接 STDIO Server
Client 可以启动一个本地 MCP Server 子进程。
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
const client = new Client({
name: "demo-client",
version: "1.0.0",
});
const transport = new StdioClientTransport({
command: "npx",
args: ["tsx", "src/server/index.ts"],
});
await client.connect(transport);
这里的 Transport 负责:
- 启动 Server 进程。
- 管理标准输入输出。
- 发送 JSON-RPC 消息。
- 接收 Server 返回的消息。
- 处理连接终止。
Client 不需要自己实现 JSON-RPC 编解码。
7.4 发现工具列表
连接成功后,可以获取 Server 提供的工具。
const result = await client.listTools();
console.log(result.tools);
典型返回结构:
{
"tools": [
{
"name": "get_user",
"description": "根据用户 ID 查询用户信息",
"inputSchema": {
"type": "object",
"properties": {
"userId": {
"type": "string"
}
},
"required": ["userId"]
}
}
]
}
Client 可以根据工具列表构建工具注册表,供 Host 或模型使用。
7.5 调用 Tool
const result = await client.callTool({
name: "get_user",
arguments: {
userId: "1001",
},
});
console.log(result);
Client 不需要知道工具内部如何访问数据库,也不需要知道业务 API 的具体地址。
它只需要知道工具名称、参数结构和调用结果。
7.6 读取 Resource
const result = await client.readResource({
uri: "config://project",
});
console.log(result.contents);
7.7 获取 Prompt
const result = await client.getPrompt({
name: "review_code",
arguments: {
language: "TypeScript",
code: "const a = 1;",
},
});
console.log(result.messages);
以上展示的是 SDK 的高层调用接口。不同 SDK 版本的构造参数、导入路径和传输适配 API 可能不同,实际项目应以锁定版本的 API 文档为准。
八、MCP Client:工具发现与动态调用
Client 的重要能力之一,是动态发现 Server 提供的工具。
这意味着 Host 不必将所有工具名称和参数写死在代码中。
8.1 动态工具注册
假设 Client 连接了三个 Server:
- GitHub Server。
- Database Server。
- Filesystem Server。
它们分别提供不同的工具。
Client 可以统一发现工具,并构建一份工具注册表。
flowchart TD
A["MCP Client Manager"] --> B["GitHub Client"]
A --> C["Database Client"]
A --> D["Filesystem Client"]
B --> E["GitHub Tools"]
C --> F["Database Tools"]
D --> G["Filesystem Tools"]
E --> H["统一工具注册表"]
F --> H
G --> H
H --> I["Host / LLM Tool Adapter"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
8.2 工具名称冲突
不同 Server 可能注册相同名称的工具。
例如:
github.search
database.search
filesystem.search
如果只使用 search 作为全局名称,就可能出现冲突。
建议采用命名空间:
const toolRegistry = {
"github.search": {
server: "github",
tool: "search",
},
"database.search": {
server: "database",
tool: "search",
},
"filesystem.search": {
server: "filesystem",
tool: "search",
},
};
命名空间不仅解决名称冲突,还可以帮助 Host 识别工具来源和权限范围。
8.3 工具列表动态变化
Server 的工具集合可能发生变化。
例如:
- 管理员启用新的业务能力。
- 插件升级后增加工具。
- 用户权限变化。
- Server 根据配置动态注册工具。
Client 不应永久假设第一次发现的工具列表就是最终列表。
可以根据 Server 提供的列表变化通知、连接状态以及应用策略,重新获取工具清单。
同时应处理:
- 工具被删除。
- 工具参数结构变化。
- 工具名称变化。
- 权限变化。
- Server 不可用。
工具描述和参数 Schema 也需要纳入缓存版本管理,避免 Client 使用过期定义调用工具。
九、MCP Client:多 Server 连接管理
真实 AI 应用通常需要连接多个 MCP Server。
因此,不能只实现一个简单的 Client 实例,还需要建立 Client Manager。
9.1 多 Server 架构
flowchart TB
A["Host"] --> B["MCP Client Manager"]
B --> C["Client A"]
B --> D["Client B"]
B --> E["Client C"]
C --> F["GitHub Server"]
D --> G["Database Server"]
E --> H["Filesystem Server"]
F --> I["GitHub API"]
G --> J["Database"]
H --> K["File System"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style J fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style K fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
一个 Client 通常对应一个 Server 的逻辑连接。
Host 通过 Client Manager 管理多个连接,而不是将多个 Server 的通信逻辑混在一个 Client 中。