这是一篇面向 CSDN 开发者社区的 AI Agent 能力扩展教程。核心不是讲概念而是带你把 MCP 和 Skill 真正用起来先跑通一个可调用的 MCP Server再写一个自定义 Skill最后用脚本批量调用并完成效果验证。文章会给出完整目录结构、代码示例、配置方法和常见问题排查清单直接照着做即可。这次我们来看 AI Agent 能力扩展中最核心的两块MCPModel Context Protocol和 Skill。MCP 解决 Agent 怎么连接外部工具和数据源Skill 解决 Agent 怎么按专业流程处理复杂任务。两者不是同一维度的东西但配合起来能让 Agent 从“只能聊天”变成“能调工具、能按模板产出结果”。目前社区里讨论热度很高的 AI Agent、MCP Server、Agent Skill基本都围绕这两条线展开值得系统过一遍。本文会演示三件事。第一从零搭建一个 MCP Server暴露两个可调用的工具第二在主流 Agent 客户端中注册这个 MCP 服务并完成一次真实调用第三创建一个自定义 Skill让 Agent 按照指定的步骤输出结构化结果。最后还会给出一套批量任务调用脚本直接复用即可。如果你正在做 Agent 开发或者想优化 Cursor、Claude Desktop、自建 Agent 的工作流这篇文章可以直接收藏。先说结论MCP 适合做工具、数据源、文件系统的标准化接入Skill 适合做方法论的沉淀和复用。一个管“手”一个管“脑”。下面进入正题。1. AI Agent 能力扩展核心速览能力项说明核心概念MCP 是模型上下文协议用于 Agent 与外部工具/数据源通信Skill 是可复用的技能包通常以 SKILL.md 为核心解决问题MCP 解决工具接入标准化问题Skill 解决复杂任务执行流程的封装问题启动方式MCP Server 可用 Python 或 Node 实现命令启动也可接入客户端Skill 通过目录和配置文件加载主要功能工具调用、数据读取、API 对接、批量任务、结构化输出、专业技能封装适合场景本地文件管理、数据库查询、信息检索、代码评审、报告生成、业务数据处理硬件门槛无需特殊 GPU普通开发机即可运行 MCP Server 和 Skill 逻辑是否支持批量任务支持MCP 工具可按脚本循环调用Skill 可对多份输入重复执行是否支持 API支持MCP 本身基于 JSON-RPC也有官方 SDK 做编程式调用学习成本中等核心是理解协议模型、工具注册方式和上下文注入方式2. MCP 与 Skill 的基本概念与应用边界2.1 MCP 解决什么问题MCP 是一个开放协议目标是让 AI 模型在运行过程中动态发现并调用外部工具、数据资源和提示模板。它把“Agent 想用工具”和“工具具体怎么暴露”解耦。传统接法是写死函数调用每个平台一套接口MCP 让工具提供方用统一协议暴露能力Agent 端只需要实现一个 MCP Client 即可对接任何兼容 Server。从结构上看MCP 有三个核心角色MCP Server 暴露工具和数据MCP Client 发起连接并调用宿主应用比如 Claude Desktop、Cursor、自研 Agent把工具结果回传给大模型。传输层常用 stdio 或 SSE请求格式基于 JSON-RPC 2.0。这意味着我们可以用自己熟悉的语言快速写一个 Server不需要关心大模型内部实现。2.2 Skill 解决什么问题Skill 通常是一组“提示词 脚本 参考资源”的组合用于让 Agent 在特定任务上按照约定流程执行。MCP 解决的是“能不能调用外部能力”Skill 解决的是“能不能把任务做专业”。举个例子同样让 Agent 写周报普通的提示词只能得到一个粗略结果如果加载了“周报生成 Skill”Agent 会先收集本周 Commit、再按“目标、进展、风险、下一步”结构输出效果稳定得多。有些 Agent 框架里 Skill 是纯 Markdown 形式的提示词模板有些则允许附带 Python/Shell 脚本用于处理本地文件或调 API。无论实现方式如何核心思想一致把专家知识固化下来按需加载不污染普通对话的上下文。2.3 适用场景与合规边界MCP 和 Skill 适合解决以下问题需要 Agent 查询数据库、读取文件、调用内部 API。需要把重复性任务沉淀成标准流程比如代码审查、纪要总结、PPT 大纲生成。需要让多个 Agent 共享同一套工具和技能库。需要批量处理大量输入文件并通过脚本控制调用节奏。使用边界方面必须注意三条底线。第一MCP Server 如果接入本地文件或数据库一定要做最小权限控制只暴露必要的数据范围。第二不要在 Skill 或 MCP 配置中硬编码敏感密钥尤其是数据库密码、API Token。第三AI 生成结果存在幻觉和不确定性涉及关键业务决策时必须人工复核。另外如果通过 MCP 接入第三方网站或抓取他人数据要确认是否符合平台规则和版权要求。3. 环境准备与项目初始化3.1 基础环境本文的 MCP Server 示例使用 Python 实现需要准备以下环境Python 3.10 或更高版本建议使用虚拟环境隔离依赖。pip 或 uv用于安装 Python 包。Node.js 18 可选用于运行 MCP Inspector 等调试工具。一个支持 MCP 的 Agent 客户端或用官方 Python SDK 自行编写调用端。注意不同 MCP SDK 版本的方法名和参数略有差异安装时建议参考对应版本文档。以下命令是通用示例实际路径按项目调整。mkdir ai-agent-extension cd ai-agent-extension python -m venv .venv # Windows .venv\Scripts\activate # Linux / macOS source .venv/bin/activate pip install mcp[cli]安装完成后可以执行下面命令检查版本mcp --version如果提示找不到命令通常说明安装目录没有加入 PATH或者需要以模块方式运行python -m mcp --version3.2 项目目录结构建议按下面的结构组织项目后续维护起来更清晰ai-agent-extension/ ├── .venv/ ├── mcp_server.py ├── client_batch.py ├── skills/ │ └── meeting_summarizer/ │ ├── SKILL.md │ └── summarize.py ├── config/ │ └── mcp_config.json └── outputs/其中mcp_server.py是 MCP Server 入口。client_batch.py是批量调用示例。skills/存放自定义 Skill。config/mcp_config.json是客户端注册 MCP 用的配置。outputs/保存批量任务输出。不要把所有文件都堆在根目录后续模型文件、输入素材、输出结果分目录管理能少踩很多坑。4. 创建一个最简单的 MCP Server4.1 编写 MCP Server以下代码使用官方 MCP Python SDK 的 FastMCP 封装代码量最精简。它会暴露两个工具get_weather和add。生产环境下get_weather需要接入真实天气 API这里用固定结果做演示。# mcp_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(TutorialDemo) mcp.tool() def get_weather(city: str) - str: 根据城市名称返回模拟天气信息。生产环境请接入真实天气 API。 # 演示逻辑实际开发时替换为 requests 调用 return f{city} 天气晴22°C湿度 45%东南风 3 级 mcp.tool() def add(a: float, b: float) - float: 两个数字相加。 return a b if __name__ __main__: mcp.run()说明mcp.tool()装饰器会把函数注册成 MCP 工具。函数名和 docstring 会被客户端作为工具名和说明展示所以写得越清晰越好。mcp.run()默认使用 stdio 传输适合本地客户端调用如果需要 HTTP 模式可以查阅官方文档配置其他 transport。4.2 启动与验证先直接用 Python 运行确认没有报错python mcp_server.py正常情况下进程会保持前台运行等待客户端连接。但这样启动不会输出内容适合验证语法和依赖是否正确。更推荐使用 MCP Inspector 来做可视化调试。MCP Inspector 是官方提供的调试界面可以列出工具、预览参数并手动调用。参考命令如下npx modelcontextprotocol/inspector python mcp_server.py如果 Node 环境正常命令执行后会在终端打印一个本地地址打开浏览器即可看到调试界面。Inspector 中可以看到工具列表点击单个工具输入参数返回结果就会显示在右侧面板。如果 Inspector 无法启动也可以先跳过直接在客户端中注册后验证。5. 在主流 Agent 客户端中接入 MCP5.1 注册 MCP 服务以 Claude Desktop 为例注册方式是在配置文件里增加mcpServers。配置路径因操作系统和客户端版本不同有差异请以实际安装目录为准。核心配置内容如下{ mcpServers: { tutorial-demo: { command: python, args: [/绝对路径/mcp_server.py], env: {} } } }需要注意command必须是可执行命令的完整名称。如果 Python 在虚拟环境内建议写虚拟环境内的 Python 绝对路径避免找不到包。args中要使用绝对路径否则客户端可能定位不到mcp_server.py。env用于传递环境变量尽量保持为空或只放入安全变量。在 Cursor 中注册入口通常在 Settings MCP 或通过命令行/mcp打开。界面操作和配置文件本质相同最终都是生成类似的 MCP 配置。5.2 调用工具并观察结果注册成功后重启客户端然后在对话中自然描述你的需求。比如输入帮我查一下上海的天气。如果 MCP 通道正常客户端会调用get_weather工具并返回类似“上海 天气晴22°C...”的结果。注意大模型是否自动调用工具取决于提示词和工具描述所以工具说明一定要写清楚。你可以在提示词中显式要求“使用天气工具”。在调试阶段优先用 MCP Inspector 确认工具本身没问题再进客户端集成可以显著减少排查时间。6. 创建和使用 Skill6.1 Skill 目录规范Skill 的表现形式很多本文采用一个通用结构每个 Skill 一个文件夹核心是SKILL.md可选附带脚本和参考文件。例如skills/ └── meeting_summarizer/ ├── SKILL.md └── summarize.pySKILL.md用于描述 Skill 的触发条件、执行步骤和输出模板。Agent 收到任务时通过读取SKILL.md来判断是否应该启用这个 Skill。6.2 SKILL.md 模板下面是一个“会议摘要生成器”的 SKILL.md 示例--- name: meeting_summarizer description: 根据会议转写文本生成结构化摘要包含主题、结论、待办事项和风险点。 --- # 会议摘要生成器 当用户提供会议文本时按以下步骤处理 1. 提取参会人和会议时间。 2. 识别会议主题和关键结论。 3. 列出待办事项标注负责人如果文本中有。 4. 输出 Markdown 格式摘要包含“会议主题”“关键结论”“待办事项”“风险提示”四个小节。 ## 示例 输入会议记录段落输出如下格式 ## 会议主题 一句话概括 ## 关键结论 列出 2-4 条核心结论 ## 待办事项 - [ ] 事项描述 负责人 ## 风险提示 如果没有风险写“无明显风险”这样的 Skill 文件重点在于描述“怎么做”而不是“为什么”。Agent 不需要理解背景只需要按照步骤执行。越具体输出越稳定。如果 Skill 需要处理本地文件可以配合一个 Python 脚本。例如summarize.py读取一份转录文本并输出 Markdown# summarize.py import sys def generate_summary(raw_text: str) - str: lines [line.strip() for line in raw_text.splitlines() if line.strip()] # 这里只是一个简单示例实际可用大模型进一步处理 topic lines[0] if lines else 未知 return f## 会议主题\n{topic}\n\n## 关键结论\n- 待补充\n\n## 待办事项\n- [ ] 待补充仅做演示真实场景下可接入大模型 API 完成抽取。6.3 在自研 Agent 中加载 Skill如果你的 Agent 是自己写的可以写一个简单的 Skill 加载器启动时读取技能目录把 SKILL.md 内容拼到系统提示词中。示例代码如下import os SKILLS_DIR ./skills def load_skill_prompt(skill_name: str) - str: skill_path os.path.join(SKILLS_DIR, skill_name, SKILL.md) if not os.path.exists(skill_path): return with open(skill_path, r, encodingutf-8) as f: return f.read() def build_system_prompt(user_request: str) - str: system_prompt 你是专业 AI 助手。\n # 按需加载技能这里简单演示固定加载 if 会议 in user_request or 摘要 in user_request: system_prompt \n[技能meeting_summarizer]\n system_prompt load_skill_prompt(meeting_summarizer) return system_prompt在具体 Agent 流程中将build_system_prompt(user_request)返回的内容作为 system prompt再让大模型生成回答就能让 Skill 发挥作用。不要一开始就加载所有 Skill否则上下文会被无关提示词占满也会增加 token 消耗并可能干扰模型的判断。按需加载是更稳妥的做法。7. 接口 API 与批量任务实践MCP 除了在聊天客户端中使用也可以直接用 SDK 编程调用方便集成到后台服务中。7.1 用 SDK 调用 MCP 工具假设你已经在项目目录下创建了mcp_server.py可以写一个客户端脚本调用工具# client_batch.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def query_weather(city: str): server_params StdioServerParameters( commandpython, args[mcp_server.py], cwd. ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result await session.call_tool(get_weather, {city: city}) print(f{city} - {result}) if __name__ __main__: asyncio.run(query_weather(上海))这个脚本会启动一个 MCP Server 子进程连接后调用工具并打印结果。如果需要在同一会话中调用多个工具可以把async with块扩展在块内连续调用。7.2 批量任务与重试批量任务的本质是循环调用工具并处理不同的输入。下面演示一个并发调用的简化示例import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client CITIES [北京, 上海, 广州, 深圳, 杭州] async def call_one(session, city): result await session.call_tool(get_weather, {city: city}) return city, result async def main(): server_params StdioServerParameters(commandpython, args[mcp_server.py]) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tasks [call_one(session, city) for city in CITIES] results await asyncio.gather(*tasks, return_exceptionsTrue) for city, res in zip(CITIES, results): if isinstance(res, Exception): print(f{city} 调用失败: {res}) else: print(f{city} 调用成功: {res}) if __name__ __main__: asyncio.run(main())注意这里使用asyncio.gather实现并发但并发数量不宜设置过大否则会对本地 MCP Server 或底层 API 造成压力。更保守的做法是按顺序调用例如for city in CITIES每个调用间隔一段时间特别适合外部 API 有频率限制的场景。针对批量任务建议增加如下措施记录每个任务的输入、输出、耗时便于追踪。对失败的调用设置重试比如指数退避重试 3 次。将成功和失败结果分开存储避免一个异常中断整个队列。8. 性能、资源与调优建议MCP Server 本身是轻量进程不依赖特定 GPU普通 CPU 即可运行。但实际使用中性能瓶颈往往出现在几个方面。第一是 Token 消耗。MCP 返回的结果和 Skill 的提示词都会占用上下文窗口。如果工具返回一个超长 HTML 或日志大模型会消耗大量 token成本明显上升。建议在 Server 端先做截断或摘要只返回必要字段。第二是并发连接数。每个客户端连接都会启动一个 MCP Server 子进程而子进程又有自己的内存占用。如果同一台机器启动几十个不同 MCP Server内存压力会变大。实际部署时可以复用同一个 Server 进程或者把多个工具放进同一个 Server而不是拆成很多小 Server。第三是启动速度。基于 Python 的 SDK 启动时需要导入一堆依赖首次调用可能要 2-5 秒。如果对延迟敏感可以考虑用 Node 实现 MCP Server或者做长驻进程。第四是上下文中 Skill 文件过大。一个大 SKILL.md 可能几千字每个请求都带入会显著增加 token。建议把 SKILL.md 控制在几百行以内把详细资料拆分到附加文件按需读取。9. 常见问题与排查方法问题现象可能原因排查方式解决方案客户端无法发现 MCP Server配置文件路径错误或服务启动失败查看客户端日志单独运行python mcp_server.py修正路径、检查依赖安装工具调用返回空或报错MCP Server 中函数参数名称不匹配在 Inspector 中手动传参测试调整函数签名保持参数名一致找不到mcp包安装到了错误的 Python 环境检查当前虚拟环境是否激活在项目虚拟环境内重新安装mcp[cli]端口冲突或连接被拒多个 MCP 服务占用相同端口查看端口占用列表修改服务端口或使用 stdio 模式大模型不主动调用工具工具描述不够清晰查看工具列表是否正常展示优化 docstring加入触发条件示例Skill 没有生效系统提示词中没有注入 SKILL.md 内容打印拼接后的 system prompt调整加载逻辑确保调用前读取最新文件批量任务中一部分失败外部 API 限流或网络波动查看错误类型和状态码增加重试逻辑和调用间隔显存或内存占用过高同时启动过多 MCP Server查看进程列表合并工具、减少连接数或不适用 GPU 场景10. 最佳实践与安全建议基于 MCP 和 Skill 构建 AI Agent 能力扩展时建议遵循以下实践。第一是“小步快跑”。先用一个最简单的 MCP 工具跑通链路再逐步增加工具和技能。示例中的天气查询和加法函数是最小验证单元能帮助确认环境、SDK、客户端配置全链路正常。第二是“配置最小化”。MCP Server 只暴露完成任务所必需的能力。例如只读场景不要开放写操作数据库连接使用只读账号文件访问限定目录。Skill 的加载也建议按需不要全量注入。第三是“密钥隔离”。不要在 MCP Server 代码、SKILL.md 或配置文件中写死 API Key。建议通过环境变量或密钥管理服务注入并在日志中隐藏敏感字段。第四是“效果复核”。MCP 和 Skill 能提升 Agent 的自主性但生成结果仍可能出错。在自动化流程中加入人工审核环节比如在批量任务执行前设置干跑模式先看输出样例再全量执行。第五是“合规授权”。如果 MCP 需要抓取外部网页、访问第三方平台数据必须确认已获得授权并遵守平台条款。涉及个人数据时要脱敏并征得相关方同意。这也是内容生成类应用最容易忽视的环节。11. 总结与下一步MCP 和 Skill 是当前 AI Agent 能力扩展的两条主线。MCP 管工具和数据接入Skill 管专业流程沉淀。看完这篇教程建议你先动手跑通mcp_server.py在 Inspector 里调用get_weather和add然后把自定义 Skill 接入到自己的 Agent 中。整个链路只需要一个普通开发机和 Python 环境本身没有太高门槛容易踩的坑主要在依赖安装、路径配置和上下文管理上。后续可以从三个方向继续深入一是把 MCP Server 从本地工具扩展成访问真实数据库或内部 API 的服务二是构建自己的 Skill 模板库把工作流固化下来三是结合批量任务脚本把 Agent 能力接入定时任务或消息队列形成真正的自动化生产力工具。建议先把今天的最小示例保存好后续所有复杂能力都基于这个骨架扩展即可。