MCP / Agent / Skill 底层概念讲解

📑 目录

三种能力类型概览
MCP 在 IDE 里的整体架构
MCP Server 配置详解
IDE 如何把 MCP 交给 Agent
MCP 配置常见写法
Skill vs MCP 对比
其他 IDE 的 MCP 支持
本机实操检查清单
三种能力怎么选
故障排查速查

1. 三种能力类型概览

在 AI 工具链中，有三种不同的能力接入方式：

类型	是什么	例子
MCP Server	独立进程，通过标准协议暴露 tools / resources，IDE 帮 Agent 去调	MCP_DOCKER、fl-studio-mcp
Agent Skill	一份 SKILL.md 工作流说明，Agent 读文档后在终端/编辑器里执行	website-to-hyperframes
CLI 工具	普通命令行，Agent 用 Shell 跑	npx hyperframes capture、uvicorn

Skill 和 CLI 不走 MCP，而是 Agent 读说明后在终端执行命令。

2. MCP 在 IDE 里的整体架构

完整调用链路

+-----------------------------------------------------------+ | IDE（你写 prompt / Agent 模式） | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | Agent（AI） | | - 看到「可用 MCP 工具列表」 | | - 按 JSON Schema 构造参数 | | - 调用 CallMcpTool(server, toolName, arguments) | +-----------------------------------------------------------+ | MCP 协议（通常 stdio JSON-RPC） v +-----------------------------------------------------------+ | MCP Server 子进程（由 IDE 根据 mcp.json 启动） | | 例：docker mcp gateway run | +-----------------------------------------------------------+ | v +-----------------------------------------------------------+ | 外部能力：Docker、数据库、浏览器、API… | +-----------------------------------------------------------+

Agent 不会直接执行 Docker 或访问数据库，而是：
IDE 启动 MCP Server → Server 注册 tools → Agent 按名调用 tool → 结果返回对话。

3. MCP Server 配置详解

3.1 全局配置（以 Cursor 为例）

Cursor 读取全局配置文件：

路径C:\Users\<USERNAME>\.cursor\mcp.json

示例内容：

JSON{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"],
      "env": {
        "LOCALAPPDATA": "C:\\Users\\ADMIN\\AppData\\Local",
        "ProgramData": "C:\\ProgramData",
        "ProgramFiles": "C:\\Program Files"
      }
    }
  }
}

含义：Cursor 打开/需要 MCP 时，执行 docker mcp gateway run，该 Docker MCP Gateway 再挂载一批 Docker 相关 MCP 工具。

3.2 在 UI 里管理

Cursor Settings → MCP：查看每个 server 的 Connected / Error 状态
启用/禁用、重连、看日志
有时可通过图形界面添加 server（等价于写 mcp.json）

如果 MCP Server 状态显示 Error，说明 Agent 目前调不了该服务，需要先修复问题。

3.3 项目级配置（可选）

有的项目会在仓库里放：

.cursor/mcp.json — 仅当前项目额外 MCP

优先级以 IDE 官方文档为准。

4. IDE 如何把 MCP 交给 Agent

4.1 启动 Server

读取 mcp.json 配置
对每个 server 起子进程（command + args + env）
握手（MCP initialize）
拉取 tools、resources 列表

4.2 工具描述符（Schema）

IDE 会在工作区生成/同步描述：

.cursor/projects/<项目>/mcps/<server>/tools/<tool-name>.json

Agent 规则：调用前必须先读 schema，知道参数名、类型、是否必填。

如果 tools 目录下没有 .json 文件，说明服务未成功注册工具。

4.3 Agent 调用流程

用户："用 Docker 查一下容器" | v Agent 判断需要 MCP | v 读 mcps/.../tools/xxx.json（了解参数） | v CallMcpTool({ server: "MCP_DOCKER", toolName: "...", arguments: {...} }) | v IDE 转发给 MCP Server | v Server 执行，JSON 结果回到对话

若 server 报错，调用失败，Agent 应改用手动命令或提示你去 Settings 修 MCP。

4.4 Resources（只读数据）

部分 MCP 还提供 resources（文件、文档片段等），通过 FetchMcpResource 读取，同样要先看 resource 描述符。

5. MCP 配置常见写法

本地命令行方式

JSON{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

远程 SSE/HTTP Server

JSON{
  "mcpServers": {
    "remote": {
      "url": "http://localhost:8080/sse"
    }
  }
}

改 mcp.json 后通常要重启 IDE 或在 MCP 面板里 Reconnect。

6. Skill vs MCP 对比

维度	MCP	Skill
触发	Agent 调具名 tool	用户 @skill、规则匹配、或 Agent 读 SKILL.md
执行体	MCP Server 进程	Agent 自己：读文件、跑终端、写代码
配置	mcp.json	~/.cursor/skills/、.cursor/skills/、~/.agents/skills/
协议	MCP JSON-RPC	无协议，纯 Markdown 指令

Skill 实例：website-to-hyperframes

路径：~/.agents/skills/website-to-hyperframes/SKILL.md

当你发 /website-to-hyperframes 时，IDE 把 skill 内容注入对话；Agent 再执行：

npx hyperframes capture <URL> -o capture
npx hyperframes lint / validate / snapshot
npm run dev    # Studio 预览
npm run render # MP4

这是终端 + 文件，不是 MCP。

7. 其他 IDE 的 MCP 支持

IDE / 产品	MCP 支持
Cursor	原生，~/.cursor/mcp.json，Agent 集成最好
VS Code + Copilot	逐步支持 MCP（扩展/Insiders），配置类似
Claude Desktop	claude_desktop_config.json 里 mcpServers
Windsurf / Cline 等	各有 MCP 配置路径，概念相同

共同点：独立 MCP 进程 + JSON 配置 + AI 客户端调 tools。
Skill / 自定义脚本不自动变成 MCP，除非单独写 MCP Server 包装。

8. 本机实操检查清单

8.1 检查 MCP 是否正常

IDE Settings → MCP：查看各 Server 是否 Connected
若 Error：检查对应服务是否运行（如 Docker Desktop）
终端能否手动执行启动命令
修复后 Reconnect

8.2 确认 Agent 能看到哪些 MCP 工具

MCP 正常时，mcps/<server>/tools/ 下会出现各 tool 的 .json
对话里可问：“列出当前可用的 MCP 工具”

8.3 使用 Skill（与 MCP 无关）

技能在 ~/.agents/skills/ 或 ~/.cursor/skills/
对话里 @skill-name 或说明需求
Agent 模式下执行终端命令

不要把 Skill 目录当 MCP 加进 mcp.json！Skill 没有 MCP server 入口，写进去也不会变成可调用的 MCP tool。

9. 三种能力怎么选

需求：把网站做成视频

✖ 错误理解：在 mcp.json 里配置 website-to-hyperframes

✔ 正确方式：使用 Skill + npx hyperframes CLI

需求：Agent 操作 Docker 容器/镜像

✔ MCP：配置 MCP_DOCKER，修好后 Agent 调 Docker MCP tools

需求：跑 FastAPI 线索 API

✔ CLI/Shell：uvicorn app.main:app（与 MCP/Skill 都无关）

10. 故障排查速查

现象	可能原因	处理
The MCP server errored	Docker 未启动、gateway 失败	开 Docker Desktop，重连 MCP
Agent 说没有某 MCP tool	Server 未连接 / 无 tools 目录	Settings → MCP 看状态
/skill-name 无反应	Ask 模式 / 未挂 skill	切 Agent 模式，@ skill
调 MCP 参数报错	未读 tool schema	先读 mcps/.../tools/*.json
Skill 和 MCP 混淆	概念混用	Skill=文档工作流；MCP=独立服务

💡 总结一句话

IDE 通过 mcp.json 启动 MCP Server 子进程，把 tools 的 JSON Schema 暴露给 Agent；
Agent 用 CallMcpTool 间接调用。

Skill 和 CLI 不走 MCP，而是 Agent 读说明后在终端执行命令。