适合人群：

• 已经在用 Codex / Cursor / AI IDE

• 听过 MCP，但一配置就报错

• 想让 AI 真正“会用工具干活”

如果你也遇到过下面这些问题，那这篇文章就是写给你的：

• MCP 服务装了一堆，但经常连不上

• npx / Node 版本各种玄学

• Windows 环境一堆坑

• 工具是有了，但 AI 不知道什么时候该用

我会按真实上手顺序，一步一步带你把 MCP 跑通，而不是堆概念。

---

一、先搞明白一件事：MCP 到底是干嘛的？

在动手之前，先用一句“人话”解释 MCP：

MCP（Model Context Protocol）是一套让大模型“标准化使用外部工具”的协议。

它解决的不是“模型聪不聪明”，而是下面这个问题：

❌ 以前：
每接一个工具，都要单独写适配代码

✅ 现在（MCP）：
工具按协议暴露能力，模型按协议调用

你可以把 MCP 理解成：
AI 世界里的 USB 接口标准。

---

二、整体结构先看一眼（强烈建议截图保存）

MCP 实际跑起来时，结构是这样的：

Codex / IDE
     ↓
  MCP Router（可选但强烈推荐）
     ↓
  各种 MCP 服务
  ├─ 搜索
  ├─ 文档
  ├─ 任务规划
  └─ 代码语义分析

---

三、第 1 步：环境准备（90% 的坑都在这）

目标

确保 Node / npx / Python 环境 没问题
不然后面 MCP 会各种“玄学失败”

---

3.1 安装 Node.js（必须 20.x 以上）

⚠️ 重点提醒：
很多 MCP 服务在 Node 18 或更低版本会直接报错

推荐方式：用 nvm 管理 Node

Mac / Linux：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc   # 或 ~/.bashrc
nvm install 20
nvm use 20

Windows：

• 搜索 nvm-windows

• 安装后执行：

nvm install 20
nvm use 20

检查是否成功

node -v
npm -v
npx -v

✅ 三个命令都能正常输出版本，才算过关。

---

3.2 安装 uv / uvx（给 Python 写的 MCP 用）

有些 MCP 服务是 Python 写的，不装会报错。

pip install uv
pip install uvx

---

四、第 2 步：先把 Codex 本体跑通（别急着上 MCP）

目标

确保 Codex 能正常调用模型
MCP 是“外挂”，本体不通先别折腾

---

4.1 config.toml 放哪？

路径（没有就新建）：

• Windows
  C:\Users\你的用户名\.codex\config.toml

• Mac/Linux
  ~/.codex/config.toml

---

4.2 最小可用 config.toml 示例

model = "gpt-5-codex"
model_provider = "my_provider"
model_reasoning_effort = "high"
network_access = "enabled"

[model_providers.my_provider]
name = "my_provider"
base_url = "https://你的中转地址"
wire_api = "responses"

📌 说明：

• model_reasoning_effort = high：更适合写代码/分析

• wire_api 具体看你用的中转站说明

---

4.3 配置 API Key（很多人卡在这里）

CLI 模式（推荐）

写进环境变量（略）

VS Code / Cursor 插件（重点！）

插件 通常不读环境变量，必须单独配：

文件路径：

~/.codex/auth.json

内容：

{
  "OPENAI_API_KEY": "sk-xxxxxx"
}

---

五、第 3 步：为什么我强烈建议你用 MCP Router？

如果你直接在 config.toml 里这样写：

[mcp_servers.xxx]
[mcp_servers.yyy]
[mcp_servers.zzz]

你大概率会遇到：

• 启动慢

• 超时

• Windows 找不到 npx

• 一个服务挂了拖死全局

我的建议很明确：

新手 + Windows + 多工具 = 一定要用 MCP Router

---

六、第 4 步：安装并使用 MCP Router（核心步骤）

目标

用 Router 统一管理所有 MCP 服务
Codex 只连 Router 一个入口

---

6.1 在 Router 里添加 MCP 服务

推荐新手必装这几个：

服务	用途
sequential-thinking	任务规划
context7	官方文档
duckduckgo-mcp-server	搜索
serena	代码语义分析

⚠️ Serena 重要提醒：
Arguments 一定要加：

--context codex

---

6.2 安装 mcpr-cli

npm install -g mcpr-cli@latest

---

6.3 在 Router 中生成 MCPR_TOKEN

• 在 Router 中添加一个 App（比如叫 codex）

• 复制生成的 MCPR_TOKEN

---

6.4 Codex 连接 Router（最关键配置）

在 config.toml 中 只保留这一段 MCP 配置：

[mcp_servers.mcp-router]
command = "npx"
args = ["-y", "mcpr-cli@latest", "connect"]
env = { MCPR_TOKEN = "你的token" }

其他 [mcp_servers.xxx] 全部删掉。

---

6.5 Windows 用户终极避坑（强烈建议收藏）

如果上面方式连不上，用 绝对路径：

[mcp_servers.mcp-router]
command = "C:\\路径\\node.exe"
args = ["C:\\路径\\mcpr.js", "connect"]
env = {
  SystemRoot = "C:\\WINDOWS",
  COMSPEC = "C:\\WINDOWS\\system32\\cmd.exe",
  MCPR_TOKEN = "你的token"
}

找路径方法：

where node

---

七、第 5 步：让 AI 真正会用工具（AGENTS.md）

很多人做到这一步会说一句话：
“工具是有了，但 AI 怎么还是不太聪明？”

原因只有一个：
👉 你没教它什么时候该用工具

---

7.1 创建 AGENTS.md

推荐：项目根目录一个

# AGENTS.md

你是我的技术搭档，请按以下规则工作：

- 先理解需求，再动手
- 优先最小改动
- 一轮最多调用一个 MCP 工具

工具使用规则：
- 规划 → sequential-thinking
- 查官方文档 → context7
- 查最新信息 → duckduckgo
- 查/改代码 → serena

使用 MCP 后，必须在结尾输出【工具调用简报】

---

八、第 6 步：Serena 激活（很多人失败就在这）

正确姿势

进入项目目录后，在 Codex 对话框输入：

使用 serena 将当前目录激活为项目

看到它开始索引代码，说明成功。

---

九、总结：新手最稳的一条路

照这个顺序来，成功率最高：

1️⃣ Node 升到 20+
2️⃣ Codex 本体跑通
3️⃣ MCP Router 接管工具
4️⃣ config.toml 只连 Router
5️⃣ AGENTS.md 教 AI 怎么用工具
6️⃣ Serena 手动激活一次