27-MCP服务器配置与调试指南

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 mcp add <server-name> [options]

# stdio模式：本地进程
codex mcp add my-sqlite \
  --command uvx \
  --args "mcp-sqlite,mcp-sqlite,--db-path,/data/test.db"

# HTTP模式：远程服务
codex mcp add my-api \
  --url http://localhost:3000/mcp \
  --bearer-token-env-var MCP_API_TOKEN

参数详解

2.2 codex mcp get —— 查看配置详情

查看已注册Server的完整配置：

# 查看全部
codex mcp get

# 查看指定Server
codex 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配置后，立即运行