27 MCP服务器配置与调试指南——从入门到排坑
一、前言
在上篇文章中，我们了解了MCP协议的原理。现在，是时候动手了！本文将带你全面掌握在Codex中配置和管理MCP Server的每一个细节——从命令行的每一个参数，到常见错误的排查方法。
无论你是第一次配置MCP Server的新手，还是想深入了解调试技巧的老手，这篇文章都能让你满载而归。
二、codex mcp 命令全家桶
Codex提供了一组完整的codex mcp子命令来管理MCP Server。这组命令等价于手动编辑~/.codex/config.toml，但更安全（自动校验格式）、更方便（支持动态环境变量）。
2.1 codex mcp add —— 添加MCP Server
最核心的命令，用于注册一个新的MCP Server到Codex配置中。
# 语法codex mcpadd<server-name>[options]# stdio模式：本地进程codex mcpaddmy-sqlite\--commanduvx\--args"mcp-sqlite,mcp-sqlite,--db-path,/data/test.db"# HTTP模式：远程服务codex mcpaddmy-api\--urlhttp://localhost:3000/mcp\--bearer-token-env-var MCP_API_TOKEN参数详解
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
<server-name> | string | ✅ | 自定义名称，字母数字和连字符 |
--command | string | stdio模式必填 | 可执行文件路径（如uvx、npx、python） |
--args | string | 否 | 传给command的参数，逗号分隔 |
--url | string | HTTP模式必填 | MCP Server的HTTP端点 |
--bearer-token-env-var | string | 否 | 承载令牌的环境变量名 |
--env | string[] | 否 | 环境变量，格式KEY=VALUE，可重复使用 |
--transport | string | 否 | 显式指定传输方式：stdio或http |
2.2 codex mcp get —— 查看配置详情
查看已注册Server的完整配置：
# 查看全部codex mcp get# 查看指定Servercodex mcp get my-sqlite输出示例：
[mcp-servers.my-sqlite] command = "uvx" args = ["mcp-sqlite", "--db-path", "/data/test.db"]2.3 codex mcp list —— 验证连接
最重要的验证命令！它不仅是列出Server，还会实际连接每个Server并调用tools/list。
codex mcp list成功输出示例：
✓ my-sqlite (stdio): 5 tools available • sqlite_query • sqlite_create_table • sqlite_insert • sqlite_read_table • sqlite_list_tables ✓ my-api (http): 3 tools available • get_weather • search_web • translate_text失败输出示例：
✗ my-sqlite (stdio): Connection failed Error: spawn uvx ENOENT (uvx not installed, try: pip install uvx)最佳实践：每次修改MCP配置后，立即运行