[!abstract] 目标 MCP 配置不是“启动一个通用服务端口”，而是告诉某个 Host 如何连接一个具体 Server：本地 stdio 配置的是命令和参数；远程 HTTP 配置的是受保护的 MCP endpoint。

[!info] related notes

• 前置概念: MCP 协议, 本地 MCP Server
• 工具地图: MCP MOC
• 特定网关: Docker MCP Gateway
• 示例 Server: CodeGraph, Context7

MCP 客户端配置指南

先决定连接方式

Server 形态	配置需要表达什么	典型例子	何时适用
本地 stdio	可执行命令、参数、必要环境变量	CodeGraph、Nx MCP、Docker Gateway	访问本机项目或依赖本地 CLI
远程 Streamable HTTP	MCP endpoint、认证方法	Context7、托管的 SaaS MCP	能力或数据由远端维护

配置文件格式是 Host 私有的，不是 MCP 协议的一部分。不要因一个 JSON 示例能在 Claude 或 VS Code 中使用，就假设 Codex、OpenCode 也会读取它。

本地 stdio：以 CodeGraph 为例

目标成功状态：在目标 Agent 的工具列表中出现 CodeGraph，并能针对当前工作区返回符号或调用链结果。

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

这段是采用 mcpServers JSON 格式的客户端示例。Host 会负责拉起进程；不要在另一终端中常驻运行同一命令并把普通日志写入 stdout。stdin/stdout 是 JSON-RPC 通道，日志应走 stderr。

Codex

Codex 使用 ~/.codex/config.toml，不是项目的 .mcp.json。最小概念形态如下：

[mcp_servers.codegraph]
type = "stdio"
command = "codegraph"
args = ["serve", "--mcp"]

在 Windows 或多版本 CLI 环境中，必要时使用明确的可执行文件路径。配置后新开一个 Codex 会话，再检查工具是否出现。项目级 .mcp.json 是否有效，取决于宿主是否声明支持该发现规则。

Claude Code / Claude Desktop / VS Code

这类客户端通常使用 mcpServers JSON 对象；Claude Code 还可通过其命令行管理 Server。项目级配置要放在该客户端官方支持的位置（例如 Claude Code 的 .mcp.json、VS Code 的 .vscode/mcp.json），再重载客户端。

OpenCode

OpenCode 的配置使用 mcp 字段，且本地 Server 通常写成命令数组：

{
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["codegraph", "serve", "--mcp"]
    }
  }
}

远程 HTTP：以 Context7 为例

远程 MCP 不需要本机拉起可执行文件。Host 对 endpoint 建立 HTTP MCP 会话；凭据只应以环境变量、客户端密钥存储或受控 header 注入，绝不能提交到项目配置。

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

具体字段（如 header、OAuth 或 API key）必须以目标客户端与服务商当期文档为准。远程 Server 的网络、认证、限流与数据边界不同于本地 stdio；不要把它当作无权限的本地工具。

验证顺序

1. 确认命令在同一用户环境的终端中可解析，例如 codegraph --version。
2. 先在项目根目录初始化并检查工具本身的健康状态；CodeGraph 可用 codegraph status。
3. 重启或新开目标 Host 会话，检查 Server 是否成功连接、工具是否列出。
4. 调用一个无副作用的只读工具；对 CodeGraph，可查一个已知符号。
5. 若 Server 会索引或监听文件，修改一个可丢弃的小文件并确认它能同步或明确报告 staleness。

常见失败

现象	优先检查
Server 未出现	配置文件是否为目标 Host 所读取；command 是否在 Host 的 PATH 中
JSON-RPC 解析错误	stdio Server 是否向 stdout 打印了日志；日志应走 stderr
能连接但工具失败	Server 自身依赖、工作目录、权限、项目索引或环境变量
HTTP Server 连不上	URL、认证、代理、网络策略与服务端限流
配置看似正确但 Codex 未加载	是否误把 .mcp.json 当成 ~/.codex/config.toml

相关链接

• MCP 架构
• MCP transports
• 本地 MCP Server
• Docker MCP Gateway