All Pages Edit on GitHub

MCP

MCP, Model Context Protocol, 可以理解为连接 AI 应用和外部工具、数据源的通用协议。它让模型客户端用统一方式访问文件、数据库、浏览器、业务系统和内部服务。

MCP 解决的核心问题

没有 MCP 时，每个 AI 客户端都要用自己的方式接工具：

AI 客户端 A -> 自定义文件工具
AI 客户端 B -> 自定义数据库工具
AI 客户端 C -> 自定义浏览器工具

这会导致重复开发、权限难统一、工具难复用。MCP 的目标是让工具提供方按统一协议暴露能力，让客户端按统一方式发现和调用。

你可以把 MCP 理解成“AI 应用的工具连接层”。

为什么要学 MCP

MCP 适合哪些人先学

如果你只是调用模型做聊天或简单 RAG，可以晚一点学 MCP。如果你想做下面这些事情，就很值得提前学：

用一句话理解 MCP

MCP 就像 AI 应用和外部工具之间的 USB-C 接口。工具只要按照协议暴露能力，支持 MCP 的客户端就可以用统一方式发现和调用这些能力。

你应该掌握什么

Client 和 Server 怎么协作

MCP Client 通常在 AI 应用或 AI 编程工具里，负责：

MCP Server 负责：

模型本身不直接访问你的文件或数据库。真正的访问应该发生在 MCP Server 或后端服务里。

可做的 MCP Server

Server 能力
文件管理 搜索、读取、写入项目文件
数据库查询 执行受限 SQL、返回表结构和结果
浏览器工具 打开网页、截图、提取内容
团队知识库 搜索 Notion、飞书、Confluence
运维工具 查询日志、部署状态和告警

Tool、Resource、Prompt 的区别

类型 用途 例子
Tool 执行动作或计算 搜索文件、查询数据库、发起请求
Resource 暴露可读取的上下文 当前项目文件、数据库 schema、文档内容
Prompt 提供可复用提示词模板 代码审查模板、日报生成模板

Tool 设计原则

MCP 工具要尽量小而清晰。一个工具应该完成一个明确动作。

推荐：

search_files(query: string, root: string, limit: number)
read_file(path: string)
query_database(sql: string, max_rows: number)

不推荐：

run_anything(command: string)
do_task(task: string)

工具越模糊，模型越难正确使用，也越难做权限控制。

Resource 适合放什么

Resource 更适合暴露稳定、可读取的上下文，例如：

如果某个能力需要计算、搜索、写入或调用外部服务，更适合做成 Tool。

实战路线

权限和安全

MCP Server 经常连接本地文件、数据库和内部系统，所以安全设计非常重要。

最低要求：

不要依赖模型“自觉不做危险事”。权限应该由 server 端代码保证。

错误处理

MCP 工具返回错误时，要让模型知道如何恢复。

坏例子：

{ "error": "failed" }

好例子：

{
  "status": "error",
  "error_code": "ROOT_NOT_ALLOWED",
  "message": "root 不在允许搜索目录内",
  "hint": "请选择 /workspace 下的目录"
}

清晰错误能帮助 Agent 调整下一步，而不是反复调用同一个失败工具。

项目检查点

新手练习：只读文件搜索工具

目标：做一个 MCP Server，提供 search_files 工具。

输入：

输出：

注意：

进阶练习