AI Agent能力扩展：MCP工作机制+实现方式+ Skill渐进式披露+codex 接入+代码实操，深度应用全流程！-创锋一号

AI Agent能力扩展：MCP工作机制+实现方式+ Skill渐进式披露+codex 接入+代码实操，深度应用全流程！

1. 引言：AI Agent 能力扩展的三大支柱

随着大模型能力的持续提升，AI Agent 已经从「单轮问答」走向「多步骤任务执行」。要让 Agent 真正落地到复杂业务场景，必须解决三个核心问题：工具接入（如何调用外部系统）、能力渐进式披露（如何让模型在合适的时机使用合适的能力）、工程化落地（如何与现有开发工具链打通）。本文围绕 MCP 工作机制、Skill 渐进式披露、Codex 接入三条主线，配合完整代码实操，带你走通 AI Agent 能力扩展的全流程。

2. MCP 工作机制：Agent 与外部世界的「标准化接口」

2.1 什么是 MCP

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 于 2024 年底提出的开放协议，旨在为 AI 应用与外部数据源、工具之间建立一套标准化的通信方式。你可以把它理解为 AI 世界的「USB-C 接口」——无论底层是哪种模型、哪种工具，只要双方都遵循 MCP 协议，就能即插即用。

2.2 MCP 的核心架构

MCP 采用客户端-服务器架构，包含三个关键角色：

MCP Host：运行 AI 模型的主程序（如 Claude Desktop、IDE 插件），负责发起请求并处理结果。
MCP Client：嵌入在 Host 中的协议客户端，负责与 Server 建立连接、协商能力、转发调用。
MCP Server：暴露工具、资源和提示词的独立服务，可以是本地进程，也可以是远程服务。

一次完整的 MCP 调用流程如下：

Host 启动时，Client 向 Server 发送initialize请求，协商协议版本与能力。
Client 通过tools/list获取 Server 暴露的工具清单。
模型根据用户意图选择合适的工具，Client 通过tools/call发起调用。
Server 执行工具逻辑，将结果以结构化 JSON 返回给模型。

2.3 MCP 的传输层与消息格式

MCP 支持两种传输方式：stdio（本地进程间通信，适合与 IDE 插件、本地 CLI 集成）和Streamable HTTP（远程服务，适合跨网络调用）。所有消息均采用 JSON-RPC 2.0 格式封装，保证跨语言、跨平台的兼容性。

3. MCP 实现方式：从零搭建一个 MCP Server

3.1 技术选型

官方提供 TypeScript 和 Python 两种 SDK。本文以 Python 为例，因为它生态成熟、上手快，适合快速验证。先安装依赖：

pip install mcp fastmcp

3.2 实现一个「天气查询」MCP Server

下面实现一个最简单的 MCP Server，暴露一个get_weather工具：

from mcp.server.fastmcp import FastMCP 创建 MCP Server 实例 mcp = FastMCP("WeatherServer") @mcp.tool() def get_weather(city: str) -> str: """查询指定城市的天气信息""" # 这里替换为真实天气 API 调用 return f"{city} 今天晴，气温 18-25℃，空气质量优。" if name == "main": mcp.run()

启动后，该 Server 会通过 stdio 监听来自 Client 的 JSON-RPC 请求。你可以用官方mcp-inspector工具可视化调试：

npx @modelcontextprotocol/inspector python weather_server.py

3.3 在 Claude Desktop 中接入自定义 MCP Server

编辑 Claude Desktop 的配置文件（macOS 路径为~/Library/Application Support/Claude/claude_desktop_config.json）：

{ "mcpServers": { "weather": { "command": "python", "args": ["/path/to/weather_server.py"] } } }

重启 Claude Desktop 后，模型即可通过自然语言调用get_weather工具，实现「帮我查一下北京的天气」这类交互。

4. Skill 渐进式披露：让 Agent 能力「按需可见」

4.1 为什么需要渐进式披露

如果把所有工具一次性暴露给模型，会产生两个问题：一是上下文窗口被大量工具描述占满，挤压有效推理空间；二是模型在无关工具间犹豫，降低任务执行准确率。Skill 渐进式披露（Progressive Disclosure）的核心思想是：先暴露少量核心能力，根据任务进展动态加载更多技能。

4.2 分层披露策略

推荐采用三层结构：

L1 常驻工具：高频、轻量的基础能力（如文本处理、计算），始终在上下文中。
L2 按需加载：低频但可能用到的能力（如数据库查询、文件读写），通过关键词匹配或意图识别动态注入。
L3 深度技能：特定领域的复杂工作流（如数据分析报告生成），仅在用户明确表达相关需求时加载。

4.3 代码实操：基于 MCP 实现 Skill 动态加载

下面演示如何在 MCP Server 端实现「按需暴露工具」。核心思路是：Server 维护一个技能注册表，根据 Client 传入的上下文标签动态决定tools/list的返回结果。

from mcp.server.fastmcp import FastMCP mcp = FastMCP("SkillServer") 技能注册表：技能名 -> 工具函数 SKILL_REGISTRY = { "basic": ["echo", "add"], "database": ["query_sql"], "report": ["generate_report"], } 当前会话已激活的技能 active_skills = {"basic"} @mcp.tool() def echo(text: str) -> str: """回显输入文本""" return text @mcp.tool() def add(a: float, b: float) -> float: """计算两个数字之和""" return a + b @mcp.tool() def query_sql(sql: str) -> str: """执行 SQL 查询（需激活 database 技能）""" return f"执行查询：{sql}" @mcp.tool() def generate_report(topic: str) -> str: """生成数据分析报告（需激活 report 技能）""" return f"已生成关于 {topic} 的报告" 动态控制 tools/list 返回 @mcp.list_tools() def list_tools(): tools = [] for skill in active_skills: for name in SKILL_REGISTRY[skill]: tools.append(mcp.get_tool(name)) return tools 模拟：根据用户意图激活技能 def activate_skill(skill_name: str): if skill_name in SKILL_REGISTRY: active_skills.add(skill_name) if name == "main": mcp.run()

通过这种机制，模型在对话初期只看到echo和add两个工具；当用户提到「查数据库」时，Host 调用activate_skill("database")，后续tools/list才会返回query_sql。这样既节省了上下文，又避免了工具误用。

5. Codex 接入：把 Agent 能力嵌入开发工作流

5.1 Codex 是什么

Codex 是 OpenAI 推出的 AI 编程智能体，能够理解代码仓库、自主完成多文件修改、运行测试并迭代修复。将 MCP 与 Codex 结合，可以让 Codex 在编码之外，还能调用企业内部的业务系统、数据库和运维平台，真正成为「全栈开发助手」。

5.2 在 Codex 中配置 MCP Server

Codex CLI 支持通过配置文件声明 MCP Server。编辑~/.codex/config.toml：

[mcp_servers.weather] command = "python" args = ["/path/to/weather_server.py"] [mcp_servers.internal_api] command = "npx" args = ["-y", "@your-org/mcp-internal-api"]

配置完成后，在 Codex 会话中直接输入自然语言指令：

请查询订单表结构，并帮我写一个分页查询接口。

Codex 会先通过 MCP 调用query_sql获取表结构，再基于返回结果编写代码，实现「理解业务 → 生成代码」的闭环。

5.3 代码实操：Codex + MCP 实现自动化运维

下面演示一个更完整的场景：让 Codex 通过 MCP 调用部署平台的 API，完成服务状态检查和自动重启。

# deploy_mcp_server.py from mcp.server.fastmcp import FastMCP import requests mcp = FastMCP("DeployServer") @mcp.tool() def check_service(service_name: str) -> str: """检查指定服务的运行状态""" resp = requests.get(f"http://ops.internal/status/{service_name}") return f"服务 {service_name} 状态：{resp.json()['status']}" @mcp.tool() def restart_service(service_name: str) -> str: """重启指定服务""" resp = requests.post(f"http://ops.internal/restart/{service_name}") return f"服务 {service_name} 重启结果：{resp.json()['result']}" if name == "main": mcp.run()

在 Codex 中发起指令：

检查 payment-service 的状态，如果异常就重启它。

Codex 会依次调用check_service和restart_service，并根据返回结果决定是否执行重启，整个过程无需人工介入。

6. 深度应用全流程：从需求到落地的完整链路

6.1 场景定义

假设我们要构建一个「智能运维助手」，能够：

理解自然语言运维指令；
查询服务状态、日志和指标；
执行重启、扩缩容等操作；
生成运维报告。

6.2 架构设计

整体架构分为四层：

交互层：Codex CLI / Claude Desktop 作为 Host，接收用户指令。
协议层：MCP Client 负责与各 Server 通信。
能力层：多个 MCP Server 分别暴露监控、日志、部署、报表能力。
执行层：底层对接 Prometheus、ELK、K8s 等真实系统。

6.3 技能渐进式披露设计

针对运维场景，设计如下技能分层：

L1 常驻：check_service（高频查询）。
L2 按需：get_logs、get_metrics（排查问题时加载）。
L3 深度：restart_service、scale_service（用户明确授权后加载，并二次确认）。

6.4 完整代码实现

下面给出一个整合了渐进式披露的运维 MCP Server：

from mcp.server.fastmcp import FastMCP mcp = FastMCP("OpsAssistant") 技能注册 SKILLS = { "l1_basic": ["check_service"], "l2_troubleshoot": ["get_logs", "get_metrics"], "l3_operation": ["restart_service", "scale_service"], } active = {"l1_basic"} @mcp.tool() def check_service(name: str) -> str: """检查服务健康状态""" return f"{name}: healthy" @mcp.tool() def get_logs(name: str, lines: int = 100) -> str: """获取服务最近日志""" return f"--- {name} 最近 {lines} 行日志 ---" @mcp.tool() def get_metrics(name: str) -> str: """获取服务核心指标""" return f"{name}: CPU 12%, MEM 34%, QPS 2300" @mcp.tool() def restart_service(name: str) -> str: """重启服务（危险操作，需授权）""" return f"{name} 已重启" @mcp.tool() def scale_service(name: str, replicas: int) -> str: """扩缩容服务（危险操作，需授权）""" return f"{name} 已扩容至 {replicas} 个副本" @mcp.list_tools() def list_tools(): result = [] for skill in active: for tool_name in SKILLS[skill]: result.append(mcp.get_tool(tool_name)) return result def activate(skill: str): if skill in SKILLS: active.add(skill) if name == "main": mcp.run()

6.5 效果验证

在 Codex 中依次输入以下指令，观察工具加载变化：

1. 检查 payment-service 状态。（仅加载 L1 工具） 2. 查看 payment-service 最近的错误日志。（触发 L2 技能加载） 3. 重启 payment-service。（触发 L3 技能加载，并要求二次确认）

通过这种设计，模型始终只看到当前任务所需的工具，既保证了响应速度，又降低了误操作风险。

7. 最佳实践与踩坑指南

7.1 工具描述要「面向模型」

MCP 工具的描述不是给人看的，而是给模型看的。描述要包含：功能边界（做什么）、输入输出格式（参数类型和返回结构）、使用场景（什么时候该调用）。例如：

@mcp.tool() def get_user_orders(user_id: str, date_from: str = None) -> str: """查询用户订单列表。当用户询问"我的订单""买了什么"时使用。 参数：user_id 用户ID；date_from 起始日期（YYYY-MM-DD，可选）。 返回：JSON 数组，每个元素包含 order_id、amount、status。""" ...

7.2 错误处理要「可恢复」

工具调用失败时，返回的错误信息要能让模型理解并尝试修复。推荐返回结构化错误：

@mcp.tool() def query_sql(sql: str) -> str: try: result = db.execute(sql) return json.dumps(result) except SyntaxError as e: return json.dumps({"error": "SQL语法错误", "detail": str(e), "suggestion": "检查表名和字段名"})

7.3 权限控制要「分层」

危险操作（删除、重启、写操作）必须放在 L3 技能层，并增加二次确认机制。可以在工具内部增加confirm参数：

@mcp.tool() def delete_user(user_id: str, confirm: bool = False) -> str: """删除用户（危险操作）。confirm 必须为 True 才会执行。""" if not confirm: return "已取消：删除用户为危险操作，请设置 confirm=True 确认。" # 执行删除 return f"用户 {us

企业官网建设流程全解析