MCP 是什么？2026 年国内开发者怎么配置 MCP 服务器
简答：MCP 是连接 AI 应用与外部工具、数据的开放协议，适合开发者把本地脚本或远程接口接入支持 MCP 的客户端；配置时重点判断传输方式、运行环境、配置文件格式和密钥位置。
定义：MCP（Model Context Protocol，模型上下文协议）是一套基于 JSON-RPC 的开放协议，用于让 AI 应用发现并调用外部服务器提供的工具、资源和提示。
先看结论：MCP 服务器应该怎么配置
MCP 不是某一个 AI 软件，也不是单独的插件市场，而是一套连接规范。AI 应用通常作为 Host，内部创建一个或多个 Client；MCP Server 则提供工具、资源或提示。官方架构说明中，Host 负责管理客户端、权限和用户授权，Client 与单个 Server 保持独立连接，Server 可以是本地进程，也可以是远程服务。可查看 MCP 官方架构说明。
| 场景 | 传输方式 | 配置核心字段 | 适合情况 | 主要检查点 |
|---|---|---|---|---|
| 本地服务器 | stdio | command、args、env | 客户端在本机启动一个子进程 | 运行时、路径、环境变量、标准输出 |
| 远程服务器 | Streamable HTTP | url、headers或客户端认证配置 | 服务器已经部署并提供 HTTP 端点 | 域名解析、TLS、HTTP 状态码、鉴权 |
| 旧版远程服务器 | HTTP+SSE | 服务端给出的 SSE 地址或连接入口 | 兼容仍使用旧传输方式的服务端 | 客户端是否支持旧协议，是否返回 405 或 404 |
截至 2026 年 10 月 21 日，MCP 官方已发布 2026-07-28 规范；此前的 2025-06-18 资料仍常见于客户端和 SDK 文档。新旧版本在会话、HTTP 传输和能力协商上存在差异，实际连接应以客户端和服务器协商结果为准。官方发布说明见 2026-07-28 MCP 规范说明。
MCP 是什么：Host、Client、Server 有什么区别
Host 是承载 AI 对话或编程助手的应用，例如支持 MCP 的开发工具。它负责创建客户端连接、显示授权提示、控制工具调用，并决定哪些数据可以交给服务器。
Client 是 Host 内部负责连接某一个 MCP Server 的连接器。一个 Host 可以管理多个 Client，但通常一个 Client 对应一个 Server 连接。Client 负责协议初始化、能力协商、消息传输和结果回传。
Server 是提供能力的一方，可以暴露三类常见内容：
- Tools：可由模型调用的函数，例如查询数据、读取文件或执行受限操作。
- Resources：可供用户或模型读取的上下文和数据。
- Prompts：预先定义的提示模板或工作流。
因此，“配置 MCP 服务器”通常不是在配置 AI 模型本身，而是在告诉 Host：用什么命令启动服务器，或者访问哪个远程端点，以及需要传入哪些参数。MCP 官方规范把这些消息编码为 JSON-RPC，并明确区分 Host、Client 和 Server，详见 MCP 规范概览。
配置前准备：先确认运行环境和服务器来源
- 确认你是在使用现成服务器，还是自己开发服务器。使用现成服务器时，重点是读取其 README，确认启动命令、参数、环境变量和支持的传输方式；自己开发时，还需要选择 SDK、编写工具处理逻辑并进行协议测试。
- 确认运行时。Node.js 服务器通常需要 Node.js 和 npm；Python 服务器通常需要 Python 与对应虚拟环境；Docker 服务器需要 Docker 命令可用。不要把未核实的版本号直接写进配置，版本要求以服务器发布页或项目文档为准。
- 确认配置格式。不同 Host 的字段名和文件位置不完全一致。VS Code 当前文档同时说明了 VS Code 格式的
servers对象，以及可移植格式中使用的mcpServers对象，不能把两种格式混用。可查看 VS Code MCP 配置参考。 - 确认权限范围。服务器可能读取文件、访问网络或执行命令。先查看工具列表和代码来源，再决定是否授权。MCP 官方规范要求实现方建立用户同意、数据保护和工具安全机制，但协议本身不能替你判断某个服务器是否可信。
国内开发环境中，如果 npm 安装、Git 仓库下载或远程端点访问失败，应先把问题拆成 DNS、TCP、TLS、HTTP 和客户端配置几层，不要一开始就反复修改 JSON。可参考本站的五层连接路线和故障基线记录。
本地 MCP 服务器怎么配置：stdio 最小模板
stdio 适合本地集成。客户端启动服务器子进程，服务器从标准输入读取 JSON-RPC 消息，再把协议响应写到标准输出。官方传输规范要求标准输出只能包含有效 MCP 消息，普通日志应写到标准错误，否则可能导致 JSON-RPC 解析失败。具体规则见 MCP 传输规范。
下面是常见的本地配置结构，字段含义如下：
command：启动程序，例如npx、python或绝对路径。args：传给启动程序的参数数组，每个参数单独写成一个字符串。env：传给子进程的环境变量，例如 API 密钥或工作目录参数。cwd：部分客户端支持的工作目录字段；如果当前客户端文档未声明支持，不要直接添加。
Node.js 服务器示例：
{"mcpServers":{"local-tools":{"command":"npx","args":["-y","your-mcp-package"],"env":{"API_KEY":"${env:API_KEY}"}}}}
Python 服务器示例：
{"mcpServers":{"local-python":{"command":"python","args":["C:\\path\\to\\server.py"],"env":{"API_KEY":"${env:API_KEY}"}}}}
Windows 路径中的反斜杠需要在 JSON 中写成两个反斜杠；macOS 和 Linux 可以使用类似 /Users/name/project/server.py 或 /home/name/project/server.py 的路径。若使用 VS Code 专用格式，结构可能是 {"servers":{"local-tools":{"type":"stdio","command":"npx","args":["-y","your-mcp-package"]}}}，应以当前文件中的顶层对象要求为准。
- 先在终端单独执行启动命令，确认程序不会立即退出。
- 如果服务器支持 MCP Inspector，先使用项目文档给出的命令测试工具列表。
- 再将同样的命令和参数写入客户端配置。
- 重启客户端或重新加载 MCP 配置。
- 在工具列表中确认服务器已连接，再进行一次无副作用的测试调用。
远程 MCP 服务器怎么配置：Streamable HTTP 与 SSE
远程服务器通常通过 HTTP 端点连接。当前 MCP 规范中的 Streamable HTTP 使用一个 MCP endpoint 接收 POST，也可以通过 GET 建立服务器消息流；客户端需要支持 application/json 和 text/event-stream。官方规范还要求服务端校验 Origin，并建议本地服务只绑定 localhost、远程服务实施认证。可查看 Streamable HTTP 传输说明。
常见配置形态如下：
{"mcpServers":{"remote-tools":{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer ${env:MCP_TOKEN}"}}}}
但这里有一个重要限制：type、headers、环境变量表达式和认证字段是否可用，取决于具体客户端。VS Code 的专用格式和可移植格式并不完全相同；Cursor 文档则使用 mcpServers、command、args、env 等字段，并区分项目配置文件 .cursor/mcp.json 与全局配置文件 ~/.cursor/mcp.json。可查看 Cursor MCP 配置说明。
如果服务器只支持旧式 HTTP+SSE，先确认客户端是否仍兼容该传输方式。不要把一个普通网页地址、健康检查地址或文档地址直接当成 MCP endpoint；应使用服务器文档明确给出的 MCP 连接地址。若返回 404、405 或 HTML 页面，先检查 URL、路径、请求方法和传输类型。
VS Code、Cursor 和其他客户端的配置差异
| 客户端 | 常见配置位置 | 常见顶层字段 | 适用判断 |
|---|---|---|---|
| VS Code | 工作区 .vscode/mcp.json、用户配置或可移植配置文件 | servers 或 mcpServers | 先确认当前使用的是 VS Code 格式还是 Copilot 可移植格式 |
| Cursor | 项目 .cursor/mcp.json 或用户目录下的 ~/.cursor/mcp.json | mcpServers | 项目配置只对当前项目生效，全局配置影响所有项目 |
| 其他支持 MCP 的客户端 | 由客户端自行规定 | 可能不同 | 以该客户端官方文档为准，不要照抄其他客户端文件 |
VS Code 文档还说明，工作区、用户配置和 Copilot 可移植配置在传输类型、工作目录、环境文件和输入变量支持上存在差异。配置完成后，应通过客户端提供的服务器列表、输出日志或工具列表确认实际加载的文件，而不是只检查文件是否存在。
如果你使用的是国内开发工具或国产 AI 编程助手，优先寻找其设置页中的“MCP”“工具”“外部服务器”或“模型上下文协议”入口，并核对它要求的字段名。没有公开文档的字段不要自行推断，写成“未核实”更安全。
密钥、环境变量和远程访问怎么处理
不要把 API Key、SecretId、SecretKey、数据库密码或长期令牌直接写入提交到 Git 的配置文件。更稳妥的做法是：
- 把密钥放入本机环境变量或客户端提供的安全输入机制。
- 配置文件只引用变量名，例如
${env:MCP_TOKEN}，不要写真实值。 - 把包含密钥的文件加入
.gitignore，提交前检查 Git diff。 - 为服务器设置最小权限，只开放实际需要的目录、接口和操作。
- 远程连接使用 HTTPS，并确认服务器文档说明的认证方式、请求头和权限范围。
需要注意，环境变量由启动服务器的那个进程读取。你在一个终端窗口设置变量，不代表图形化客户端一定能读到；Windows、macOS、Linux 的图形化启动方式也可能有不同的环境继承结果。VS Code 官方文档明确提醒，不要把令牌、密码或已填充的认证请求头提交到共享配置中，可查看 认证与密钥配置说明。
MCP 连接失败怎么排查：按这个顺序定位
- 服务器进程是否启动：在终端直接执行
command和args，观察是否立即退出。立即退出通常与路径、运行时、依赖或权限有关。 - 标准输出是否被日志污染：stdio 服务器如果把普通文本写到 stdout，客户端可能报 JSON 解析错误。将日志改写到 stderr。
- 配置文件是否被客户端读取：检查文件路径、顶层字段、JSON 逗号和引号，并确认当前打开的是正确的工作区或用户配置。
- 工具列表是否为空：先看服务器是否完成初始化和能力协商，再检查服务器是否真正注册了工具；“服务器已连接”不等于“已经提供工具”。
- 远程地址是否可达：先用
nslookup example.com或curl -I https://example.com/mcp检查 DNS 和 HTTP，再看 TLS 证书、返回状态码和响应类型。 - 认证是否正确：确认令牌变量在客户端启动的进程中存在，确认请求头名称、Bearer 格式和权限范围与服务端文档一致。
- 版本或传输不兼容：检查服务器支持 stdio、Streamable HTTP 还是旧式 SSE，并查看日志中的协议版本、初始化失败或 404/405 信息。
若你看到“Unexpected token”“Invalid JSON”“工具列表为空”“Connection closed”或“Unsupported protocol version”，不要同时修改多个设置。先保存原始配置和日志，再一次只改一个变量。网络层问题可使用本站的分层诊断检查表；如果怀疑客户端设置影响请求，可继续检查系统代理与浏览器代理冲突排查。
使用现成 MCP 服务器和自己开发服务器有什么区别
| 任务 | 你需要准备什么 | 验证方式 | 常见风险 |
|---|---|---|---|
| 使用现成服务器 | 读取项目文档，准备运行时、命令、参数和密钥 | 启动进程、查看工具列表、执行无副作用调用 | 来源不明、权限过大、依赖安装失败、字段格式不匹配 |
| 自己开发服务器 | 选择 SDK，定义工具输入输出，实现业务逻辑和传输层 | 单元测试、协议检查、Inspector 或客户端实际连接 | stdout 污染、输入校验不足、权限边界不清、远程认证缺失 |
如果只是把一个本地脚本接入 AI 客户端，先从现成的 stdio 示例开始；如果要让多个客户端或多台设备访问，再评估 Streamable HTTP、认证、日志、并发和部署问题。MCP TypeScript SDK 的官方入门示例要求 Node.js 20 或更高版本，并演示了工具注册、stdio 启动和使用 Inspector 调试；但这只是该 SDK 示例的要求，不代表所有 MCP 服务器都需要相同版本。可查看 MCP TypeScript SDK 官方入门。
常见问题
MCP 是什么，和普通 API 有什么区别？
MCP 是面向 AI 应用的标准化连接协议，除了传输请求，还定义了工具、资源、提示、能力协商和生命周期。普通 API 通常只描述某个业务接口，是否能被 AI 客户端发现和调用要由应用自行实现。
国内开发者配置 MCP 服务器一定要用远程服务器吗？
不一定。个人开发和本地工具优先考虑 stdio，本地客户端启动子进程即可；需要多客户端或集中部署时，才考虑 Streamable HTTP。具体能否使用，还取决于客户端支持的传输类型和服务器文档。
MCP 配置文件里的 command、args、env 分别是什么？
<code>command</code> 是启动程序，<code>args</code> 是传给程序的参数数组，<code>env</code> 是启动子进程时注入的环境变量。JSON 中每个参数应单独放在数组元素里，密钥尽量通过环境变量传入。
为什么 MCP 服务器启动了，但客户端显示没有工具？
服务器进程启动只说明程序存在，不代表初始化、能力协商和工具注册都成功。先查看客户端输出日志，再确认服务器是否注册 tools、stdout 是否被日志污染，以及客户端是否读取了正确配置文件。
Streamable HTTP 和 SSE 有什么区别？
Streamable HTTP 是当前规范中的远程传输方式，使用 MCP endpoint 接收 POST，并可使用 GET 建立事件流；HTTP+SSE 是较早的传输方式。连接前应以服务器和客户端文档声明的支持范围为准，不要只根据 URL 外观判断。
MCP 配置中的 API Key 可以直接写进 JSON 吗？
技术上有些客户端允许，但不建议把真实密钥写入共享配置或代码仓库。优先使用环境变量、客户端输入变量或其他安全凭据机制，并检查文件权限、Git 提交记录和服务器最小权限范围。