MCP 是 Codex 连接外部世界的标准化协议，它让模型能够访问第三方文档或与开发者工具（如浏览器、Figma）交互。

原理：MCP 使用 JSON-RPC over stdio 作为通信机制，核心抽象是“命名方法调用 + 结构化结果”。Codex 作为MCP Host（主机），连接到各个 MCP Server（服务器）。
服务器定义：一个 MCP 服务器会定义模型可调用的工具、工具的输入/输出模式、认证授权要求以及结构化结果等。它提供了实时信息和受控操作，而 Skill 则提供了围绕这些工具的工作流指导。

目录结构

MCP 的目录结构可以从三个层面来理解：MCP 服务器自身源码的项目结构、Codex 中 MCP 配置文件的存放位置，以及插件中 MCP 配置的组织方式。

MCP 服务器项目结构（源码层面）

如果你要自己开发一个 MCP 服务器，推荐的目录结构取决于语言和技术栈。

基础 Python 服务器（适合简单工具）

使用官方脚手架生成的基础结构非常简洁：

my-server/  
├── server.py # 主服务器文件，包含工具定义和启动逻辑  
├── pyproject.toml # 项目配置和依赖声明  
├── .gitignore # Git 忽略规则  
└── README.md # 项目说明文档

server.py 中定义工具的核心模式：

from mcp.server.fastmcp import FastMCP  
mcp = FastMCP("my-server")  
@mcp.tool()  
async def example_tool(text: str) -> str:  
    """一个处理文本的示例工具。"""  
    return f"Processed: {text}"  
if __name__ == "__main__":  
    mcp.run()

进阶 Python 服务器（生产级）

AWS Labs 的 MCP 服务器设计指南推荐以下结构，强调单一职责和明确的入口点：

mcp-server-project/  
├── README.md  
├── pyproject.toml  
├── awslabs/ # 源码根目录（命名空间）  
│ └── your_mcp_server/  
│ ├── __init__.py # 版本元数据  
│ ├── models.py # 数据模型和校验逻辑  
│ ├── server.py # MCP 服务器实现 + main() 入口  
│ └── consts.py # 常量定义  
└── tests/ # 测试目录

关键规范：不要创建单独的 main.py，入口点函数 main() 应定义在 server.py 内部，并在 pyproject.toml 中注册：

[project.scripts]  
"awslabs.your-mcp-server" = "awslabs.your_mcp_server.server:main"

TypeScript 服务器（模块化分工）

TypeScript 模板将工具、资源和提示模板按功能拆分到独立目录：

mcp-server-template/
├── src/
│   ├── index.ts              # 主入口，服务器启动和注册
│   ├── tools/                # 工具实现（模型可调用的函数）
│   │   └── example.ts
│   ├── resources/            # 资源实现（模型可访问的数据）
│   │   └── example.ts
│   └── prompts/              # 提示模板（可复用的提示结构）
│       └── example.ts
├── dist/                     # 编译输出（自动生成）
├── package.json
├── tsconfig.json
└── CLAUDE.md                 # 给编码代理的项目说明

生产级三层架构（复杂服务器）

对于需要处理认证、多租户、审计等企业级需求的服务器，推荐三层分离的架构：

service-name-mcp/  
├── src/  
│ ├── transport/ # 第一层：传输与协议  
│ │ ├── stdio.ts # STDIO 传输  
│ │ ├── http.ts # HTTP + SSE 传输  
│ │ └── session.ts # 会话管理  
│ ├── protocol/ # 第二层：MCP 协议  
│ │ ├── mcp-server.ts # MCP 服务器主实现  
│ │ ├── tool-registry.ts # 工具注册与分发  
│ │ ├── resource-registry.ts  
│ │ └── prompt-registry.ts  
│ └── business/ # 第三层：业务逻辑  
│ ├── services/ # 核心业务服务  
│ ├── clients/ # 外部 API 客户端  
│ └── transformers/ # 数据转换工具  
├── auth/ # 认证与授权  
├── security/ # 安全工具（限流、脱敏）  
├── audit/ # 审计日志  
└── observability/ # 监控与追踪

核心原则：传输层不包含业务逻辑，协议层只负责工具注册和分发，业务层完全独立于 MCP 协议，可单独测试。

Codex 中 MCP 配置的目录位置

Codex 不使用 .mcp.json 作为主配置文件，而是将 MCP 服务器配置统一存放在 config.toml 中。

全局配置

~/.codex/config.toml 是 Codex 的总控配置文件，MCP 服务器在此注册：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.my-http-server]
url = "https://example.com/mcp"
bearer_token_env_var = "MY_API_TOKEN"

项目级配置（仅限受信任项目）

在受信任的项目中，可以创建 .codex/config.toml 来限定 MCP 服务器的作用范围：

<项目根>/
├── .codex/
│   └── config.toml      # 项目专属的 MCP 服务器配置
├── src/
└── ...

CLI 管理命令

也可以完全通过 CLI 命令管理，无需手动编辑文件：

# 添加 STDIO 服务器

codex mcp add context7 -- npx -y @upstash/context7-mcp

# 添加带环境变量的服务器

codex mcp add my-server --env API_KEY=xxx -- npx -y my-mcp-server

# 在 TUI 中查看活跃的 MCP 服务器

/mcp

插件中 MCP 配置的目录结构

当 MCP 服务器需要随插件分发时，使用 .mcp.json 文件，该文件位于插件根目录（不在 .codex-plugin/ 内部）。

插件目录布局

docs-helper/                      # 插件根目录
├── .codex-plugin/
│   └── plugin.json               # 插件清单，声明 MCP 配置路径
├── .mcp.json                     # MCP 服务器定义（根目录）
└── skills/
    └── docs-search/
        └── SKILL.md

plugin.json 中的引用

{
  "name": "docs-helper",
  "version": "1.0.0",
  "description": "Find answers in OpenAI developer documentation.",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

路径规则：从插件根目录解析，必须以 ./ 开头，不能包含 ..，必须停留在插件内部。

.mcp.json 的内容

插件中的 .mcp.json 使用 mcpServers 包装器，与 Codex 全局配置中的 [mcp_servers] 表结构不同：

{
  "mcpServers": {
    "openai_docs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

支持两种传输类型：

类型	配置字段	说明
`stdio`	`command`、`args`、`env`	本地进程，Codex 启动命令来运行
`http`	`url`	远程 HTTP 端点

MCP