Cursor 的 MCP 配置不生效：配置位置与作用域先分清
「我 mcp.json 明明写了，聊天里就是看不到这个工具。」遇到这种情况，值得先怀疑的往往不是 JSON 写错了，而是那份 JSON 不在 Cursor 会去读的位置上，或者读到了但被别的机制挡在执行前面。
MCP 服务器本身怎么写、通用的 mcp.json 字段长什么样，站内另有一篇专门讲 Claude Code 与 Cursor 通用配置的教程。这一篇只做 Cursor 侧的配置位置与作用域，以及配置看起来没生效时按什么顺序确认。
依据只有 Cursor 官方文档 cursor.com/docs/mcp 与 cursor.com/help/customization/mcp 两页。该产品迭代频繁，文中涉及的设置项与字段随版本变动，请以官方文档最新内容为准。
先把「有几处能配」数清楚
手写文件的两处，官方文档在「Configuration locations」一节写明：
- 项目级：在项目里创建
.cursor/mcp.json，用于项目专属的工具 - 全局级：在主目录创建
~/.cursor/mcp.json，用于到处都能用的工具
Help 页把两者关系说得更明确：两份文件是合并的；同一个 server name 在两边都出现时，项目级配置优先。这是排查里最常用的一条——在全局改了半天没反应，很可能是项目里那份同名条目一直压着它。
另外两处不是文件：Team 管理员在 Dashboard > Integrations & MCP 下配置共享的 Team MCP 服务器，文档写明这些服务器对 Cloud Agents 可用；Help 页则写明 Cloud Agents 支持在 Cloud Agents dashboard 里配置的服务器。本地那份 .cursor/mcp.json 和 Cloud Agent 看到的工具，文档是分开叙述的两套来源。要让一台已有的 Team MCP 服务器同时出现在 Agent Window、IDE 和 CLI 里，文档给的动作是在 Team MCP Servers 下选择 Add to Team Marketplace。
还有一处给自动化用：文档「Extension API reference」写明可用 vscode.cursor.mcp.registerServer() 以编程方式注册服务器，不必改 mcp.json。机器上有企业初始化脚本时，这条线索别漏。
Windows 上注意：文档一律写 ~/.cursor/mcp.json，对应你的用户主目录，官方文档没有写明 Windows 下的具体展开路径。配置里要引用主目录用 ${userHome}，要拼路径分隔符用 ${pathSeparator} 或 ${/}，同一份配置才能在 Windows 与 macOS/Linux 上都成立。
排查一：服务器到底起没起来
现象：聊天里没有这个 MCP 的工具，或者工具在但调用直接失败。
怎么确认：文档 FAQ 里给了明确的判定动作——看 MCP 日志。
- 打开 Output 面板（Help 页写明快捷键：macOS 为 Cmd + Shift + U，Windows/Linux 为 Ctrl + Shift + U）
- 在下拉里选择 MCP Logs
- 看有没有连接错误、认证问题或服务器崩溃
文档写明日志里会有服务器初始化、工具调用和错误信息。日志里有初始化记录，说明配置被读到了，问题在服务器进程或认证；日志里根本没有这台服务器，说明配置层面就没被加载，往下走第二步。
处置：本地 stdio 服务器起不来，先核对 command。文档对这个字段的要求写得很死：必须在系统 path 上可用，或者写出完整路径。文档给的这两个选项里，写完整路径少一层不确定性——Cursor 进程拿到的 PATH 与你终端里的 PATH 是否一致，官方文档没有说明这一点，写全路径就不用赌（这属于通用做法，不是官方文档的建议）。
怎么验证：Help 页的处置是「保存文件并重启 Cursor」，然后回 MCP Logs 看有没有新的初始化记录。
什么情况说明不是这个原因：日志里这台服务器初始化正常、工具也列在 Available Tools 里，那就不是启动问题，别再折腾 command，直接跳到排查四。
排查二：它被关掉了，或者你改的是另一份文件
现象：日志里完全没有这台服务器的任何记录。
怎么确认：文档 FAQ 写明服务器可以被临时禁用——在侧边栏打开 Customize（Help 页给的路径是 Customize > MCPs），用开关启用或禁用；被禁用的服务器不会加载，也不会出现在聊天里。日志一片空白，先看这个开关。
开关是开的，就核对你改的是哪份文件：按合并规则项目级同名条目优先，全局文件里你刚改的那条可能自始至终没参与过。
处置：确认项目根目录下有没有 .cursor/mcp.json、里面有没有同名 server name。要团队共享，Help 页给的做法是把项目级那份提交到 git。
怎么验证：改完重启 Cursor，回 MCP Logs 看初始化记录。
什么情况说明不是这个原因：如果这是管理员分发的服务器，开关和你的文件都不是关键。文档写明把 MCP 服务器链接到 marketplace 并不会替所有人安装或启用它，同事那边还得自己从 Customize 里安装配置。
排查三：环境变量与插值的作用范围
现象：服务器起来了，但一调用就报认证失败，或者拿不到 API key。
怎么确认：先看你把变量放在哪了。文档「Config interpolation」一节写明，Cursor 只在这五个字段里解析变量：command、args、env、url、headers，其它字段没有列进去；静态 OAuth 的 auth 对象文档单独说明同样支持插值。可用写法是 ${env:NAME}、${userHome}、${workspaceFolder}、${workspaceFolderBasename}、${pathSeparator} 与 ${/}。
一个容易踩的定义问题：文档把 ${workspaceFolder} 定义为包含 .cursor/mcp.json 的那个项目根目录，定义直接绑在项目级配置文件上。全局配置里写这个变量会解析成什么，官方文档没有说明这一点，别赌。
第二个坑是 envFile。文档在 STDIO 字段表里把它写为「加载更多变量的环境文件路径」，紧接着补了一句：envFile 只对 STDIO 服务器可用，远程服务器（HTTP/SSE）不支持 envFile；远程服务器要用环境变量，文档给的做法是改用 config interpolation，配合 shell profile 或系统环境里设置的变量。
处置：本地服务器把密钥交给 env 或 envFile，远程服务器走 headers 加插值。文档里的远程示例：
{
"mcpServers": {
"remote-server": {
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
}
}
}
}
真实密钥别写进仓库里那份文件，用插值引用 <YOUR_API_KEY> 对应的环境变量名。文档安全一节口径一致：用环境变量存密钥，永远别硬编码。
怎么验证：Help 页的排查条目很直白——服务器依赖 shell profile 里的环境变量时，要确保这些变量对 Cursor 可用，并且更新 shell profile 之后要重启 Cursor，重启后再看日志里还有没有认证错误。Windows 侧要说清楚：文档这条讲的是 shell profile，Windows 上环境变量的设置方式文档没有对应说明，能确定的只有「变量要对 Cursor 进程可见」和「改完重启」。
什么情况说明不是这个原因：日志里没有任何认证或变量相关报错、工具也列出来了，就别在环境变量上耗着。
排查四：起来了，但每次都在等你点确认
现象：工具在列表里，服务器也正常，但 Agent 没有「自动」用上它。这一类严格说不是配置不生效，是审批机制在起作用，但表现上很容易被当成配置问题来查。
怎么确认：文档写明 Cursor 默认在使用 MCP 工具前会请求批准，并且 MCP 与终端命令走同一套 run mode。文档举的例子是：在 Auto-review 模式下，allowlist 内的 MCP 工具立即运行，其余的走分类器。Help 页补了版本口径：在 Cursor 3.6 及以上，Cursor Settings > Agents > Approvals & Execution 里的默认模式是 Auto-review；Allowlist 保持此前只认 allowlist 的行为。
处置：Help 页写明，要预先配置哪些工具免批准运行、或从外部引导 Auto-review 的分类器，对应的是 permissions.json，细节在 cursor.com/docs/reference/permissions 那一页，本文不展开。
怎么验证：文档写明 Cursor 会在聊天里展示工具响应，参数与响应都可展开查看。
什么情况说明不是这个原因：压根没出现过任何批准请求、工具名也没在会话里出现过，问题就在前面三步。文档写明 MCP 工具在 Plan Mode 里同样会被使用，在 Plan Mode 里看不到它同样回排查一。
排查五：远程服务器的 OAuth 回调没登记全
现象：远程服务器（url 形式）授权流程走不完。
怎么确认：文档写明 Cursor 对 MCP 服务器使用固定的 OAuth redirect URL，要为用户会用到的每个入口分别登记回调：
https://www.cursor.com/agents/mcp/oauth/callback
http://localhost:8787/callback
对应关系是：前者用于 Web 与 Cursor Agents，后者用于 Desktop app。两端都会授权时，文档要求两个都登记为允许的 redirect URI。文档还写明服务器通过 OAuth 的 state 参数识别，所以这两个固定回调对所有 MCP 服务器都适用。
处置：提供方给的是固定 Client ID、或要求登记 redirect URL、或不支持 OAuth 2.0 动态客户端注册时，文档给的做法是在远程条目上加 auth 对象：CLIENT_ID 必填，CLIENT_SECRET 选填（提供方使用机密客户端时才需要），scopes 选填——省略时 Cursor 会通过 /.well-known/oauth-authorization-server 发现 scopes_supported。
怎么验证：回 MCP Logs 看认证相关错误是否消失。
什么情况说明不是这个原因：本地 stdio 服务器不走这套。文档把 stdio 的 Auth 列为 Manual，只有 SSE 与 Streamable HTTP 两种远程传输在表里标 OAuth——传输方式一共三种，认清自己用哪种再决定要不要查 OAuth。
排查六：企业侧把它挡住了
现象：个人配置怎么改都不生效，尤其在公司发的设备上。
怎么确认：文档写明企业管理员可从 Cursor dashboard 控制用户能运行哪些 MCP 服务器，入口是 Team Settings > MCP Configuration。allowlist 的三类条目是：Command entries 按命令模式批准本地 stdio 服务器，URL entries 按 URL 条目模式批准远程 HTTP/SSE 服务器，Tool allowlists 限制某台已批准服务器里哪些工具可以自动运行（留空表示允许全部）。
网络是分开的一层：远程 MCP 的 URL 被限制在配置的 URL 条目模式内；本地命令型服务器按每台的网络模式来，文档列了四档——Allow all、Allowlist（只允许列出的目的地）、Deny all、No sandbox（不带命令与网络 sandbox 运行）。管理员也可以允许用户配置管理员模式之外的自有 MCP，这类不匹配的用户 MCP 可用 User MCP Network Denylist 阻断匹配的网络目的地。
处置：这一层不是在本地改文件能绕开的，把服务器命令或 URL 提给管理员按上述条目批准。文档单独强调了一句：allowlist 只是批准一份 MCP 配置，不负责分发或安装服务器。
怎么验证：还是看 MCP Logs，错误性质是否从网络/权限类变成正常初始化。
什么情况说明不是这个原因：个人设备、没加入团队的账号不涉及这一层。
最后：这些情况根本不是配置问题
有几种表现，文档已经写明是预期行为，别往配置上归因：
- 单台服务器崩溃或超时。文档写明此时 Cursor 会在聊天里报错、该次调用标记为失败，可以重试或查日志，其它 MCP 服务器继续正常工作，Cursor 会隔离单台服务器的故障。「只有一台不工作」本身就指向那台服务器，不是配置整体。
- npm 系服务器版本旧了。文档给的更新流程是：从 Customize 里移除该服务器 → 执行
npm cache clean --force→ 重新添加以获取最新版本；自建服务器则是更新本地文件后重启 Cursor。改配置解决不了版本问题。 - 工具就是没被选中。文档只说 Cursor 会在相关时自动使用
Available Tools下列出的工具，也可以按名字点名。模型某次对话里选不选它，文档没有给出可配置的判定规则，别当成 bug 查配置。
顺序别乱：先用 MCP Logs 判断「有没有被加载」，再看开关和文件层级，然后是变量与插值，最后才轮到审批与企业策略。反过来查，最常见的结局是在一份正确的 JSON 上改出一堆错误。
本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。
该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现；
我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。
该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。
本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。