【Agent】MCP协议介绍、MCP Server服务端开发与 Skills技能编写

【Agent】MCP 协议介绍、MCP Server 服务端开发与 Skills 技能编写

1、MCP 协议介绍（Agent+MCP Client）

1.1 MCP 是什么（想解决什么问题）

1.2 MCP 的核心角色与关系（Agent、MCP Client、MCP Server）

1.3 APP = Agent + MCP Client（codex、cursor、opencode、openclaw 应该怎么理解）

1.4 MCP 暴露的核心能力有哪些（Tools，Resources，Prompts）

1.5 一次典型的 MCP 调用流程、MCP 与传统插件体系的区别

2、MCP Server 开发

2.1 MCP Server 本质上在做什么、适合做成 MCP Server 的能力

2.2 开发一个 MCP Server 的基本步骤（概要设计）

2.3 一个最小示例（例子）

2.4 MCP Server 的设计建议、容易踩的坑（详细设计）

2.5 MCP Server 的常见落地场景（平台类、知识类、协同类）

3、Skills 技能编写

3.1 Skills 是什么、与 MCP 的关系、与 AGENTS.md的关系、Skills 的触发机制

3.2 一个 Skill 的典型目录结构、SKILL.md 里通常写什么（概要设计）

3.3 一个最小 Skill 示例（例子）

3.4 写好 Skill 的几个原则（详细设计）

3.5 什么时候该写 Skill，什么时候该写 MCP Server

小结

参考资料

文章目录

- [1、MCP 协议介绍（Agent+MCP Client）](#1、MCP 协议介绍（Agent+MCP Client）)
- - [1.1 MCP 是什么（想解决什么问题）](#1.1 MCP 是什么（想解决什么问题）)
  - [1.2 MCP 的核心角色与关系（Agent、MCP Client、MCP Server）](#1.2 MCP 的核心角色与关系（Agent、MCP Client、MCP Server）)
  - [1.3 APP = Agent + MCP Client（codex、cursor、opencode、openclaw 应该怎么理解）](#1.3 APP = Agent + MCP Client（codex、cursor、opencode、openclaw 应该怎么理解）)
  - [1.4 MCP 暴露的核心能力有哪些（Tools，Resources，Prompts）](#1.4 MCP 暴露的核心能力有哪些（Tools，Resources，Prompts）)
  - [1.5 一次典型的 MCP 调用流程、MCP 与传统插件体系的区别](#1.5 一次典型的 MCP 调用流程、MCP 与传统插件体系的区别)
- [2、MCP Server 开发](#2、MCP Server 开发)
- - [2.1 MCP Server 本质上在做什么、适合做成 MCP Server 的能力](#2.1 MCP Server 本质上在做什么、适合做成 MCP Server 的能力)
  - [2.2 开发一个 MCP Server 的基本步骤（概要设计）](#2.2 开发一个 MCP Server 的基本步骤（概要设计）)
  - [2.3 一个最小示例（例子）](#2.3 一个最小示例（例子）)
  - [2.4 MCP Server 的设计建议、容易踩的坑（详细设计）](#2.4 MCP Server 的设计建议、容易踩的坑（详细设计）)
  - [2.5 MCP Server 的常见落地场景（平台类、知识类、协同类）](#2.5 MCP Server 的常见落地场景（平台类、知识类、协同类）)
- [3、Skills 技能编写](#3、Skills 技能编写)
- - [3.1 Skills 是什么、与 MCP 的关系、与 AGENTS.md的关系、Skills 的触发机制](#3.1 Skills 是什么、与 MCP 的关系、与 AGENTS.md的关系、Skills 的触发机制)
  - [3.2 一个 Skill 的典型目录结构、SKILL.md 里通常写什么（概要设计）](#3.2 一个 Skill 的典型目录结构、SKILL.md 里通常写什么（概要设计）)
  - [3.3 一个最小 Skill 示例（例子）](#3.3 一个最小 Skill 示例（例子）)
  - [3.4 写好 Skill 的几个原则（详细设计）](#3.4 写好 Skill 的几个原则（详细设计）)
  - [3.5 什么时候该写 Skill，什么时候该写 MCP Server](#3.5 什么时候该写 Skill，什么时候该写 MCP Server)
- 小结
- 参考资料

1、MCP 协议介绍（Agent+MCP Client）

1.1 MCP 是什么（想解决什么问题）

MCP，Model Context Protocol，可以理解为面向大模型应用的"上下文与工具接入协议"。

它要解决的核心问题是：模型本身会推理，但它拿不到企业内部系统、数据库、文档平台、工单系统、代码仓库等外部上下文，也无法稳定地调用这些系统完成动作。

如果每个 Agent、每个 IDE、每个桌面客户端都自己定义一套工具协议，那么生态会非常碎片化，服务端也要重复适配。

MCP 的价值就在这里：

对上，给 Agent / IDE / AI Client 提供统一的接入方式
对下，给业务系统、内部平台、SaaS 服务提供统一的暴露方式
中间，把"模型可读上下文"和"模型可调用能力"标准化

一句话概括：

MCP 想做的，是 AI Agent 时代的标准化扩展接口层。

MCP 想解决什么问题

如果没有 MCP，一个典型企业场景通常会遇到下面几个问题：

模型知道怎么回答，但拿不到最新数据
模型知道应该调用系统，但不知道该怎么调用
不同 AI 产品接不同工具，各写各的适配层
一个工具接入好几个 Agent 时，要重复开发多套插件
权限、审计、参数校验、安全边界都容易失控

MCP 的目标不是让模型"更聪明"，而是让模型更容易拿到正确上下文，并通过受控方式调用外部能力。

1.2 MCP 的核心角色与关系（Agent、MCP Client、MCP Server）

很多文章会把 Agent、MCP Client、MCP Server 混在一起讲。实际上它们不是同一层概念。

Agent

Agent 不是 MCP 协议里的正式角色，更像是一个 产品形态或运行时概念。
它通常包含：
一个或多个大模型
Prompt 编排
记忆或会话状态
任务规划与执行逻辑
工具调用能力
可能还包含代码执行、文件操作、浏览器自动化等能力
所以，Agent 可以理解为 "会思考、会决策、会调用工具的 AI 应用"。

MCP Client

MCP Client 是 MCP 协议中的正式角色。
它的职责是：
连接 MCP Server
发现服务器暴露的能力
把能力注册给上层 Agent 或宿主应用
按协议格式发送请求、接收结果
也就是说，MCP Client 是 Agent 与 MCP Server 之间的"协议适配层"。

MCP Server

MCP Server 也是 MCP 协议中的正式角色。
它负责把外部系统能力暴露出来，供 MCP Client 调用。它可以封装：
工具调用能力，例如创建工单、查询告警、重启服务
资源读取能力，例如读取文档、配置、数据库视图
预置提示词能力，例如某个领域任务的模板化 Prompt
可以把它看成"面向模型的服务适配器"。

Agent、MCP Client、MCP Server 三者关系

最容易理解的方式是看一条调用链：

text 复制代码

用户 -> Agent -> MCP Client -> MCP Server -> 外部系统

进一步拆开就是：

text 复制代码

用户发起任务
  -> Agent 进行意图理解与任务规划
  -> Agent 发现当前可用的 MCP 工具/资源
  -> 通过内置的 MCP Client 发起协议调用
  -> MCP Server 转译成真实系统请求
  -> 外部系统返回结果
  -> MCP Server 封装结果
  -> Agent 基于结果继续推理或输出

因此可以这样记：

Agent 负责"做决定"
MCP Client 负责"按协议沟通"
MCP Server 负责"把外部能力暴露出来"

1.3 APP = Agent + MCP Client（codex、cursor、opencode、openclaw 应该怎么理解）

Agent 有哪些？MCP Client 有哪些？

这个问题常见，但要注意：Agent 与 MCP Client 不是互斥分类。
很多产品既是 Agent 运行环境，也内置了 MCP Client。
例如：
Claude Desktop / Claude Code：是 Agent 产品，同时也是 MCP Client 宿主
Cursor：是 IDE 型 AI Agent，也能作为 MCP Client 接入外部 MCP Server
Codex：作为编码 Agent/终端工作流产品，也可以通过其宿主能力接入 MCP Server
OpenCode：更偏开源编码 Agent/CLI 形态，若实现了 MCP 接入，也可以视为带 MCP Client 的 Agent 宿主

Codex / Cursor / OpenCode/OpenClaw

这类产品更适合归为：
上层是 Agent 或 AI IDE / AI CLI
底层可能内置 MCP Client
它们本身通常不是 MCP Server；它们更像是"使用 MCP Server 的一方"。

所以更准确的问法通常不是"它到底是 Agent 还是 MCP Client"，而是：

它是不是一个 Agent 产品/运行时？
它内部有没有实现 MCP Client？
它能不能连接第三方 MCP Server？
这几个词最稳妥的分类方式是：
MCP：协议标准
MCP Client：协议调用方
MCP Server：协议提供方
Codex / Cursor / OpenCode / OpenClaw：具体产品或运行时，它们可能集成 MCP Client，但不等于 MCP 本身

1.4 MCP 暴露的核心能力有哪些（Tools，Resources，Prompts）

MCP 常见的能力类型可以概括为三类：

1、Tools

供模型发起"动作"的能力，强调执行。
例如：
查询云主机详情
创建工单
重启服务
触发部署

2、Resources

供模型读取"上下文"的能力，强调获取信息。
例如：
读取某篇文档
查看某份配置
读取某个数据库视图
获取某个项目的说明信息

3、Prompts

供宿主或 Agent 复用的提示模板，强调任务封装。
例如：
"代码评审助手"
"事故复盘助手"
"云资源巡检助手"

从落地角度看：

Tools 更像可执行 API
Resources 更像只读上下文接口
Prompts 更像可复用任务模板

1.5 一次典型的 MCP 调用流程、MCP 与传统插件体系的区别

一次典型的 MCP 调用流程：

Agent 启动时连接一个或多个 MCP Server
MCP Client 与服务端完成握手与能力发现
Agent 得到当前可用的 tools、resources、prompts 列表
用户提问后，模型判断是否需要调用某个 MCP 能力
Agent 通过 MCP Client 按协议发起调用
MCP Server 访问真实系统，并把结果返回给 Agent
Agent 再决定是继续调用，还是给用户最终答复

所以 MCP 解决的不是"模型推理流程"，而是 "模型怎么安全、统一地接外部世界"。

MCP 与传统插件体系的区别

可以把 MCP 理解为一种更通用的"AI 工具协议"，它和传统浏览器插件、IDE 插件、Bot 插件体系相比，有几个明显差异：
它是面向模型和 Agent 的，而不是只面向 GUI
它同时覆盖"读上下文"和"做动作"
它强调标准协议，而不是每个宿主各搞一套插件接口
它更适合一份服务端能力被多个 AI Client 复用

对于企业来说，这一点非常重要：

与其给每个 AI 产品各写一个插件，不如把企业能力统一封装成 MCP Server。

2、MCP Server 开发

2.1 MCP Server 本质上在做什么、适合做成 MCP Server 的能力

MCP Server 的本质工作其实不复杂：

把你的业务能力整理出来
用 MCP 协议把这些能力暴露成标准接口
让上层 Agent 能发现、理解并调用它们

所以写 MCP Server，本质不是"重新发明业务逻辑"，而是 "给已有系统加一层面向模型的接入层"。

适合做成 MCP Server 的能力

通常下面这些能力都很适合做成 MCP Server：

查询型能力：查资源、查账单、查日志、查文档
运维型能力：重启、扩缩容、发布、巡检
协作型能力：建工单、发通知、拉群、排班
知识型能力：暴露内部知识库、规范文档、FAQ
平台型能力：把一批内部 API 聚合成统一工具层

不太适合直接暴露的能力包括：

没有权限隔离的高危操作
参数边界极难收敛的危险能力
缺少审计、回滚、确认机制的生产变更操作

2.2 开发一个 MCP Server 的基本步骤（概要设计）

可以按下面顺序推进：

1、先定义你要暴露什么能力

不要一上来就写代码，先把接口想清楚：
是 tool、resource 还是 prompt
输入参数是什么
输出结果是什么
谁能调用
哪些动作需要鉴权、审计、二次确认

2、把底层系统能力封装成稳定函数

最好的做法是先写普通业务函数，再把它注册给 MCP Server。
不要把业务逻辑、参数校验、权限判断全部混在 MCP Handler 里。

3、给模型设计"易理解"的接口

面向模型暴露能力时，接口命名和描述非常重要。
建议：
工具名使用动词开头，例如 list_instances、restart_service
参数名清晰，不要使用内部缩写
描述里说明适用场景、限制条件、危险提示
结果尽量结构化，避免纯长文本

4、补齐安全治理

至少要考虑：
鉴权
审计
限流
超时
幂等
高危操作确认
错误处理与脱敏

5、在真实 Client 中联调

Server 单独跑起来不代表能用，还要在真实 MCP Client 中验证：
能否被发现
描述是否足够让模型选中
参数是否容易调用成功
错误信息是否足够帮助模型纠正输入

2.3 一个最小示例（例子）

下面用 Python 举一个极简示意。重点不是语法细节，而是理解结构。

python 复制代码

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ops-helper")


@mcp.tool()
def get_instance_status(instance_id: str) -> dict:
    """Query the current status of a cloud instance by instance ID."""
    # 这里一般会去调用真实云平台 API
    return {
        "instance_id": instance_id,
        "status": "running",
        "region": "cn-east-1",
    }


@mcp.resource("doc://runbook/restart-service")
def restart_runbook() -> str:
    return "1. Confirm traffic drain. 2. Restart service. 3. Check health."


if __name__ == "__main__":
    mcp.run()

这个示例表达了三件事：

通过 FastMCP 创建一个服务
用装饰器注册 tool
用装饰器注册 resource

实际项目里，你通常还会继续补：

鉴权中间层
日志与审计
异常处理
调用下游平台 SDK 或 HTTP API
更严格的参数校验

2.4 MCP Server 的设计建议、容易踩的坑（详细设计）

MCP Server 的设计建议

1、接口要"面向任务"，不要只"面向底层 API"

例如底层有 10 个云主机查询接口，不一定都原样暴露。
更好的方式是封装成更符合任务目标的能力，例如：
list_project_instances
get_instance_cost_summary
find_idle_disks
这样 Agent 更容易用对。

2、返回结构化结果

结构化输出比大段自然语言更适合 Agent 后续处理。
优先返回：
JSON 对象
明确字段
稳定枚举值
可分页、可过滤结果

3、把危险操作和查询操作分开

例如：
查询类：默认开放
变更类：要求更高权限
高危类：要求确认、审计甚至人工审批
不要把"查看实例"和"删除实例"做成同一类宽泛接口。

4、错误信息要可纠正

错误信息不要只返回 failed 或 500 error。
更好的做法是告诉 Agent：
哪个参数错了
合法值是什么
是否可以重试
这样模型才有机会自动修正调用。

开发 MCP Server 时最容易踩的坑

暴露的粒度太底层，导致模型不会用
没有权限边界，导致高危操作直接裸奔
接口描述太弱，导致 Agent 不知道什么时候调用
返回结果太散乱，导致模型拿到结果也难继续推理
只做 happy path，没有考虑失败重试和错误提示
业务逻辑直接写进协议层，后续维护会越来越乱

所以，MCP Server 开发的关键不只是"协议接通"，而是：

让 Agent 能理解、能安全调用、能稳定调用、能调用成功。

2.5 MCP Server 的常见落地场景（平台类、知识类、协同类）

企业里比较常见的几类实践：

1、平台类 MCP Server

把云平台、容器平台、监控平台、工单平台统一封装成工具层。
例如：
查询主机、云盘、网络
查询告警
获取账单
执行巡检

2、知识类 MCP Server

把企业内部知识变成资源接口。
例如：
架构文档
运维手册
值班流程
产品说明

3、协同类 MCP Server

把通知、审批、工单、发布、排障流程串起来。
例如：
创建故障工单
推送飞书/Slack/邮件通知
拉取复盘模板
生成变更摘要

3、Skills 技能编写

3.1 Skills 是什么、与 MCP 的关系、与 AGENTS.md的关系、Skills 的触发机制

MCP 解决"怎么连接外部能力"，Skills 解决"拿到能力后，Agent 应该按什么套路做事"。

Skills 是什么

Skills 不是 MCP 协议的一部分。
它更接近某些 Agent 产品中的 "能力打包机制"或"专业化工作说明书" 。
以 Codex 这类产品为例，Skill 通常是一组本地化、可复用、可按需触发的任务说明，目的是让通用 Agent 在某个领域里表现得更专业、更稳定。
可以把 Skill 理解成：
一份领域化操作手册
一套可复用工作流
一组附带脚本、参考资料、模板资源的任务包

Skills 与 MCP 的关系

这两者经常一起出现，但不是同一个层次。
MCP 更像"连接层"： 它负责：连接工具、连接知识、连接外部系统
Skills 更像"行为层" ：它负责：
规定任务流程、
约束读取哪些资料、
指导优先用哪些脚本、模板、资源、
告诉 Agent 在什么场景下采用什么做法、
因此，一个成熟 Agent 往往同时具备：
MCP Server：提供外部能力
Skills：提供领域流程
二者结合起来，效果通常最好。

AGENTS.md：告诉 Agent 应该怎么工作。 Skill：告诉 Agent 某类任务具体怎么做。 MCP Server：给 Agent 提供可读可调用的外部能力

Skills、AGENTS.md、MCP Server 三者区别

1、AGENTS.md
更像项目级、仓库级、会话级的长期指令。

它主要告诉 Agent：

当前仓库有哪些约定

有哪些可用技能

触发技能的规则是什么

本项目希望 Agent 如何协作
它偏"全局规则"。
2、Skill
更像某个具体领域或任务的专用操作包。
它偏"局部能力"与"专项工作流"。
3、MCP Server

它是能力提供方。
它偏"外部系统接入"。

Skills 的触发机制怎么理解

一个 Skill 通常不是永远加载进上下文，而是按需触发。
常见触发方式包括：
用户明确点名某个技能
用户需求明显符合某个技能描述
当前仓库的 AGENTS.md 里规定了该类任务必须使用某个技能
所以写 Skill 时，name 和 description 不只是"文档标题"，而是触发线索的一部分。

3.2 一个 Skill 的典型目录结构、SKILL.md 里通常写什么（概要设计）

一个 Skill 的典型目录结构

一个 Skill 最核心的文件通常是 SKILL.md，此外还可以带资源文件。

text 复制代码

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── helper.py
├── references/
│   └── domain-guide.md
└── assets/
    └── template.md

可以这样理解：

SKILL.md：必需，写技能说明与触发条件
scripts/：放可执行脚本，解决高重复、高确定性任务
references/：放参考资料，按需加载
assets/：放模板、图标、样板文件等输出资源

SKILL.md 里通常写什么

一个好的 SKILL.md 一般包含两部分：
1、Frontmatter 元数据

这部分最重要，因为它直接影响技能是否会被触发。

最常见的是：

yaml 复制代码

---
name: cloud-cost-review
description: Review cloud cost anomalies, identify likely waste, and propose actionable optimization steps for monthly FinOps analysis.
---

2、正文说明

正文一般写：
这个技能什么时候该用
进入任务后先做什么
需要查哪些参考资料
优先调用哪些脚本
输出结果应该长什么样
有哪些限制与注意事项

3.3 一个最小 Skill 示例（例子）

下面给一个简单示意：

markdown 复制代码

---
name: mcp-server-review
description: Review MCP server implementations for tool design, security boundaries, and protocol ergonomics.
---

# MCP Server Review

## When to use

Use this skill when the user asks to design, review, or refactor an MCP server.

## Workflow

1. Read the server entry file and exposed tools.
2. Check authentication, authorization, timeout, and audit handling.
3. Verify tool names, descriptions, and parameter clarity.
4. Prefer scripts in `scripts/` for repeatable validation.

## References

- For security checklist, read `references/security.md`
- For API naming patterns, read `references/naming.md`

这个 Skill 虽然很小，但已经具备几个关键点：

能描述触发场景
能规定工作步骤
能指导读取额外资料
能约束输出关注点

3.4 写好 Skill 的几个原则（详细设计）

1、短而清晰

不要把 SKILL.md 写成一本手册。
Skill 不是知识库索引全集，而是"让 Agent 快速进入正确工作方式"的说明。

2、只写模型本来不知道的东西

如果是通用常识，就没必要重复写。
真正有价值的是：
组织内约定
业务规则
特定流程
特定脚本入口
特定输出格式

3、把大段资料放进 references/

SKILL.md 负责导航，详细资料放到 references/。
这样可以避免一次性把大量无关内容塞进上下文。

4、把确定性强的步骤做成脚本

如果某段逻辑总是重复写、而且必须稳定，最好做成 scripts/。
Skill 里直接告诉 Agent 优先使用脚本，而不是每次现场手写。

5、输出格式要明确

例如明确要求输出：
调研结论
风险列表
修复建议
命令示例
最终 Markdown 文档
这样 Agent 的结果会更稳定。

3.5 什么时候该写 Skill，什么时候该写 MCP Server

这是实践里最关键的一道判断题。

更适合写 Skill 的情况

你想沉淀某个领域工作流
你想约束 Agent 的做事方式
你有一堆参考资料、模板、脚本需要复用
你不一定需要连接外部实时系统

更适合写 MCP Server 的情况

你要接入实时数据
你要接入企业平台或 SaaS
你要让 Agent 可执行某类系统动作
你要把能力标准化给多个 Client 复用

两者一起用的情况

这是最常见、也最有价值的方式：
用 MCP Server 提供实时能力
用 Skill 规定调用顺序、分析方法、输出格式

例如一个"云成本巡检 Agent"就可以这样拆：

MCP Server：查询账单、查询资源、查询标签、查询利用率
Skill：规定先看 Top 成本项，再看异常增长，再做优化建议，最后按固定模板输出

小结

如果只记住一句话，可以记这组分工：

MCP 是协议，负责统一 Agent 与外部能力的连接方式
MCP Client 是调用方，负责按协议与 Server 通信
MCP Server 是提供方，负责把工具、资源、提示暴露出来
Agent 是上层运行时，负责理解任务、规划步骤和调用能力
Skill 是 Agent 层的专业化工作包，负责让 Agent 在某类任务上做得更稳

所以，做 AI 基础设施时，三件事通常要分开看：

用 MCP 解决"接什么、怎么接"
用 MCP Server 解决"企业能力怎么标准化暴露"
用 Skills 解决"Agent 拿到这些能力后，应该按什么流程工作"

这三层配合起来，才比较接近一个可用、可扩展、可治理的企业级 Agent 体系。