客户端配置与宿主集成

多数场景你不需要自己写客户端程序，而是把服务器"登记"进宿主应用——Claude Desktop、VS Code、Cline、Cursor 等都内置了 MCP 客户端。登记的方式大同小异：一份 JSON 配置声明服务器叫什么、用什么命令启动。本章以最常见的配置写法为主线，具体路径以各家官方文档为准。

通用结构：mcpServers

几乎所有宿主的配置都围绕 mcpServers 这个顶层键，value 是一个服务器名到启动参数的映射：

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/Users/me/docs"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "换成你的令牌" }
    }
  }
}

含义：宿主启动子进程执行 command + args，把 stdio 当 MCP 传输；env 里放服务器需要的环境变量（如令牌）。第二项键值因宿主而异，部分宿主用 type/url 表示远程 HTTP 服务器，均以各家文档为准。

为什么 command 常用 npx / uvx

npx（Node）与 uvx（Python）都是"临时拉取并运行工具"的命令行：配置里写 npx/uvx，首次连接会自动下载对应服务器，免去手动安装。代价是首次启动较慢、需要网络，且依赖 node/uv 环境。若服务器是本地脚本，command 也可以直接写 python 或可执行文件的绝对路径。

Claude Desktop 的配置

配置文件名固定为 claude_desktop_config.json：macOS 在 ~/Library/Application Support/Claude/，Windows 在 %APPDATA%\Claude\ 下（准确路径以官方文档为准）。菜单栏可打开该文件，编辑后必须完全重启 Claude 才生效。日志与排错也在官方文档列出的目录中。

VS Code / Cline / Roo Code 类 IDE

VS Code 生态（含 Cline、Roo Code 等扩展）通常在设置里维护 mcpServers 或各自的 JSON 配置文件：值结构与上文一致，改完需重载窗口或重启扩展。Roo Code 的 MCP 文件与 Cline 的 cline_mcp_settings.json 都遵循同一套 command/args/env 写法，个别字段差异看各自仓库 README。

Cursor 等新工具

Cursor 等新兴工具同样把"接入 MCP server"作为标准能力，配置入口一般在设置或服务器面板中，支持本地 stdio 与远程 HTTP 两种方式，以官方文档为准。

本地 stdio 与远程 HTTP 两种登记

上文示例都是"本地 stdio 型"：宿主启动子进程，通信走标准输入输出。若服务器已经按第 15 章部署成 HTTP 服务，宿主配置改用远程型登记——用 type 声明 http、url 指向端点、headers 携带令牌：

{
  "mcpServers": {
    "remote-demo": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer 你的令牌" }
    }
  }
}

官方已弃用旧的 SSE 传输，新配置不要填 type: sse。远程型字段在不同宿主里写法略有出入（有的省略 type、有的用 url 直接推断），以各家文档为准。

写配置时的常见坑

JSON 是严格格式：不支持注释、不允许尾逗号，粘贴前先做语法校验；
Windows 路径里的反斜杠要写成 \ 转义，或统一用正斜杠 / 更省心；
env 里的密钥不要提交进版本库，尽量用宿主提供的密钥存储或环境变量引用；
一个 command 被多个服务器复用时留意参数冲突；npx/uvx 各自按需下载，反而相互隔离；
配完先在终端手动跑一遍 command + args，确认服务器本身能启动，再排查配置问题。

排错速查

配置不生效时按下面顺序排查：改动后是否重启了宿主；command 是否在 PATH 中（或改用绝对路径）；node/uv 是否安装；首次用 npx/uvx 需网络下载，耐心等待或看终端日志；宿主自带的日志文件能给出子进程报错（如 Claude 的日志目录、VS Code 输出面板），stdio 服务器的自身日志在 stderr 里（详见第 18 章）。小结：宿主集成 = 写一份 mcpServers JSON——本地用 command/args 描述启动命令（常配 npx/uvx），远程用 type/url 指向 HTTP 端点；各家入口与路径不同但结构相通，改动后重启并查日志即可排错。

笔记加载中…

标签：#MCP

返回知识库