官方原文索引： Model Context Protocol (MCP) / MCP Servers
1. 核心架构与原理解析
MCP（Model Context Protocol）是 OpenAI 推出的标准化工具集成协议，允许 Codex 调用外部系统（数据库、浏览器、文档平台、GitHub 等）。
MCP vs 传统工具调用的区别：
| 维度 | 传统 Function Call | MCP |
|---|---|---|
| 协议 | 各平台私有 | 标准化 JSON-RPC |
| 发现 | 硬编码 | 运行时自动发现工具列表 |
| 上下文 | 单次调用 | 可维护跨调用状态 |
| 生态 | 孤立 | 跨平台复用（Claude、Codex 等） |
MCP 架构拓扑：
MCP 传输方式：
| 方式 | 适用场景 | 启动方式 |
|---|---|---|
| stdio | 本地工具（文件系统、数据库客户端） | Codex 启动子进程 |
| HTTP/SSE | 远程服务（文档平台、云 API） | 独立运行，Codex 连接 |
2. 工程落地与代码示例
安装 MCP 服务器
# 列出已配置的 MCP
codex mcp list
# 添加 Context7 文档 MCP
codex mcp add context7 npx -y @upstash/context7-mcp
# 查看特定 MCP 配置
codex mcp get context7
# 在交互会话中查看可用工具
> /mcp配置 MCP（config.toml）
# 全局 MCP 配置
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "${DATABASE_URL}" }
# HTTP 模式 MCP
[mcp_servers.docs]
url = "https://developers.openai.com/mcp"实战：文档查询 MCP
# 启动会话
> use context7
> React 19 的 use API 和 Suspense 的最佳实践是什么？
# Codex 会自动调用 context7 MCP 查询最新文档
# 然后基于查询结果给出建议实战：GitHub MCP 代码审查
# 查询 PR 详情
> use github
> 查看 openai/codex 仓库最近的 5 个 PR，分析它们的代码质量趋势
# Codex 调用 GitHub MCP 获取数据，然后生成分析报告实战：数据库 Schema 分析
# 连接数据库分析表结构
> use postgres
> 分析 users 表和 orders 表的关联关系，生成 ERD 描述
# Codex 调用 PostgreSQL MCP 查询 information_schema
# 然后输出表关系分析自定义 MCP Server（开发示例）
// 简单的 MCP Server 示例（stdio 模式）
// my-mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = new Server(
{ name: 'my-api-server', version: '1.0.0' },
{ capabilities: { tools: {} } }
);
server.setRequestHandler('tools/list', async () => {
return {
tools: [
{
name: 'query_internal_api',
description: '查询内部 API 的状态',
inputSchema: {
type: 'object',
properties: {
endpoint: { type: 'string', description: 'API 端点' },
},
required: ['endpoint'],
},
},
],
};
});
server.setRequestHandler('tools/call', async (request) => {
if (request.params.name === 'query_internal_api') {
const { endpoint } = request.params.arguments;
// 调用内部 API...
return { content: [{ type: 'text', text: `API ${endpoint} 状态正常` }] };
}
throw new Error('Unknown tool');
});
const transport = new StdioServerTransport();
await server.connect(transport);3. 场景深入：MCP 在团队中的落地
场景：技术文档自动同步
场景：内部工具链集成
4. 💡 核心避坑与最佳实践 (Takeaways)
- 优先配置文档类 MCP：如 Context7、官方文档 MCP，让 Codex 获取最新 API 信息而非依赖训练数据
- stdio MCP 会占用进程：每个 stdio MCP 是独立进程，过多会导致资源占用上升
- 敏感 Token 用环境变量：不要在 config.toml 中硬写密钥，使用
${ENV_VAR}引用 - MCP 不是万能药：本地文件操作、代码编辑仍由 Codex 原生处理，MCP 解决的是"外部活数据"问题
- 自定义 MCP 遵循协议规范：确保实现
tools/list和tools/call两个核心接口 - 监控 MCP 调用延迟：慢速 MCP 会拖慢 Agent 响应，必要时加缓存或超时控制