---
title: "接入 MCP 工具和上下文"
description: "Model Context Protocol 把 Codex 连接到外部工具、文档、数据源和可执行动作。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Model Context Protocol（MCP）把 Codex 连接到外部工具和上下文。你可以用 MCP 读第三方文档，也可以操作开发工具，例如浏览器、Figma、GitHub 或 Sentry。

> [!CAUTION]
> MCP 不只是“多一点资料”。带写权限或外部动作的 MCP server 会扩大风险边界，必须先看 token、工具白名单、审批和日志。

<Cards>
  <Card title="MCP" href="https://developers.openai.com/codex/mcp">
    官方 Codex MCP 配置说明。
  </Card>
  <Card title="MCP tools guide" href="/docs/codex/understanding/mcp-tools-guide">
    理解 tool、resource、prompt 和权限差异。
  </Card>
  <Card title="Config basics" href="/docs/codex/official/02-config-security/06-basic-config">
    MCP 配置跟随 `config.toml` 加载层和项目 trust 边界。
  </Card>
</Cards>

## 两类 server

```mermaid
flowchart LR
    Codex["Codex"] --> Stdio["STDIO server"]
    Codex --> HTTP["Streamable HTTP server"]
    Stdio --> Local["local command"]
    HTTP --> Remote["remote service"]
```

STDIO servers 作为本地进程运行，由命令启动。适合本机文档、浏览器、开发工具或需要本地环境的集成。

Streamable HTTP servers 通过地址访问，适合远程托管系统。它们可以使用 bearer token，也可以走 OAuth。服务器支持 OAuth 时，用：

```bash
codex mcp login <server-name>
```

## 配置位置

Codex 把 MCP 配置和其他配置一起放在 `config.toml`：

```text
~/.codex/config.toml
```

项目级配置可以放在：

```text
.codex/config.toml
```

项目级配置只会在 trusted projects 中加载。CLI 和 IDE extension 共享配置，配好后不用重复设置。

## 用 CLI 管理

添加 STDIO server：

```bash
codex mcp add <server-name> --env VAR=VALUE -- <stdio server-command>
```

示例：

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

查看命令：

```bash
codex mcp --help
```

TUI 中用 `/mcp` 查看 active MCP servers。

## 用 config.toml 管理

每个 server 使用 `[mcp_servers.<server-name>]` table。

STDIO server 常见字段：

- `command`
- `args`
- `env`
- `env_vars`
- `cwd`
- `experimental_environment`

HTTP server 常见字段：

- `url`
- `bearer_token_env_var`
- `http_headers`
- `env_http_headers`

通用控制项：

- `startup_timeout_sec`
- `tool_timeout_sec`
- `enabled`
- `required`
- `enabled_tools`
- `disabled_tools`

OAuth callback 需要固定端口或 URL 时，再配置 `mcp_oauth_callback_port` 和 `mcp_oauth_callback_url`。

## 最小样例

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

HTTP server：

```toml
[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
enabled_tools = ["search", "read"]
```

不要把 token 直接写进配置。用环境变量、secret store 或系统凭据管理。

## 选择 MCP server

常见选择：

- OpenAI Docs MCP：搜索和阅读 OpenAI developer docs。
- Context7：连接开发者文档。
- Figma：访问 Figma designs。
- Playwright：控制和检查浏览器。
- Chrome Developer Tools：检查 Chrome。
- Sentry：访问 production error context。
- GitHub：管理 pull requests、issues 和 review data。

优先接只读工具。写入型工具必须先定义审批、日志和回滚方式。

## 验收清单

- server 能启动或认证成功。
- token 不在仓库、日志和 prompt 中出现。
- `enabled_tools` / `disabled_tools` 收窄到任务需要。
- timeout 合理，失败时能定位是启动、认证还是工具调用问题。
- 项目级 MCP 只在 trusted project 中加载。
- 外部工具输出被当作不可信输入处理。

## 官方资料

- [Codex MCP](https://developers.openai.com/codex/mcp)
- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
- [MCP tools guide](/docs/codex/understanding/mcp-tools-guide)
