---
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="/zh-Hant/docs/codex/understanding/mcp-tools-guide">
    理解 tool、resource、prompt 和許可權差異。
  </Card>
  <Card title="Config basics" href="/zh-Hant/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](/zh-Hant/docs/codex/understanding/mcp-tools-guide)
