浏览 MCP与Skills教程与资源
Cursor MCP 配置：项目与全局 mcp.json、工具调用及日志排查
在一个工作区接入公开文档服务，确认 Cursor 读的是哪份配置、调用了哪些工具。项目目录控制连接的加载位置，Server 和外部凭证才决定实际可访问的数据。
先决定谁需要看到这个 Server
只在当前项目使用，把定义放在项目根目录的 .cursor/mcp.json；本人所有项目通用的连接放在 ~/.cursor/mcp.json。Windows 原生的全局位置位于当前用户目录，例如 %USERPROFILE%\.cursor\mcp.json。项目配置可以随代码审查，共享的是定义，不是每位成员的登录态。
先查看这两处是否已有同名条目。本文使用唯一名称 openaiDeveloperDocs，主线只保留在项目配置中；如果公司还分发了 MCP 或通过插件安装过同一服务，应同时检查 Customize 中显示的来源。不要为了排错盲删全局文件。
本文针对 Cursor 桌面端的本机工作区。远程开发、容器和 Cloud Agent 的文件系统与环境变量可能不同，不能把本机终端的可执行路径直接复制过去。
创建项目 .cursor/mcp.json，先接无需密钥的文档服务
在你已打开的项目根目录创建 .cursor 文件夹，将下面内容保存为 mcp.json。已有文件则先备份，只在 mcpServers 中增加本例条目，保留其他字段。OpenAI Docs MCP 只提供公开文档，不需要填写 API Key。
项目范围的完整最小 JSON
{
"mcpServers": {
"openaiDeveloperDocs": {
"url": "https://developers.openai.com/mcp"
}
}
}这是 Cursor 的 mcpServers 结构。VS Code 的 .vscode/mcp.json 使用另一套包装，Claude Code 的 .mcp.json 还要求相应传输字段；不要只改文件名就混用。
在 Customize 和对话记录里核对不同事实
- 01
确认连接被加载
打开 Cursor 侧栏 Customize，找到 MCP Server 并启用本例；如本版界面仍使用旧设置分组，在设置中搜索 MCP。重新加载窗口或重启后确认状态，区分定义存在与工具可用。
- 02
发送明确的资料任务
在 Agent 对话中输入：‘请使用 openaiDeveloperDocs 查询 Codex MCP 的 user 和 project 配置位置，给出各自适用范围及来源 URL；工具不可用就报告原始错误。’默认情况下 Cursor 会要求工具审批；展开参数检查是否只查询这项资料。
- 03
核对工具的输入和响应
展开本次 MCP 调用，确认是目标 Server，并把响应中的页面与最终引用对照。预期是一份有来源的配置说明，不是凭模型记忆列出一组路径。Run Mode 可能改变审批行为，不能假设每个用户都会出现相同确认框。
- 04
打开无关工作区作对照
在没有本例项目配置的新窗口检查 Server。如果仍存在，先查全局、插件或团队分发来源；这个结果反映配置加载来源，不是外部权限是否已撤销。
变量在哪展开，命令在哪运行，必须保持一致
Cursor 支持在 command、args、env、url、headers 中使用其文档规定的变量语法。${workspaceFolder} 指包含 .cursor/mcp.json 的项目根，${env:NAME} 读取环境变量，${userHome} 指用户目录。它们属于 Cursor 解析规则；不要复制为 Claude Desktop、Claude Code 或 Codex 通用语法。
stdio 的 command 应是一个可执行程序，参数逐项放在 args 中，当前文档将 type: stdio 列为该类配置字段。Windows 的 .cmd 文件通常需正确的 cmd 包装；更稳妥的已安装 Node 方案是使用真实 node.exe 绝对路径，加已核实的 JS 入口。只有看到日志中的启动失败，才去处理程序路径。
Cursor 文档中的 envFile 适用于 stdio，不适用于 HTTP/SSE。远程服务的 header 变量取值依赖 Cursor 启动环境；你在另一个终端临时设置变量，不保证已运行的 GUI 会读取。重新启动时仍失败，要检查变量来源及企业策略，不能把真实令牌贴到 issue 或截图里。
项目配置、工具审批、Server 授权不要混为一个开关
| 控制 | 控制了什么 | 怎样检查本次问题 |
|---|---|---|
| 项目/全局配置 | 连接定义在哪些工作区加载。 | 换无关工作区观察定义来源；出现同名项时排查其他配置来源。 |
| Cursor 工具审批及 Run Mode | 某次工具调用是否直接执行、审阅或拒绝。 | 展开调用参数和审批记录；它不会把高权限 Token 自动变成只读 Token。 |
| Server 的目录与账号策略 | 实际工具执行允许访问哪些对象。 | 查看 Server 提供的范围回读，用专用样本分别核对允许与拒绝路径；不拿真实私密文件做越界测试。 |
| 上游资源授权 | 数据库、仓库或 SaaS 最后是否接受该身份的操作。 | 用实际请求身份和资源权限核对；换 Cursor 工作区不是撤销提供方授权。 |
本页文档主线没有本地文件权限，因此不声称已验证文件隔离。若另接 Filesystem，Roots 可能改变实际允许目录；应按具体实现回读，不能将 ${workspaceFolder} 文字当安全证明。
从 MCP Logs 把配置错误和调用错误分开
Windows/Linux 使用 Ctrl+Shift+U、macOS 使用 Cmd+Shift+U 打开 Output，在下拉列表选择 MCP Logs。按 Server 名和复现时间查找启动、连接及调用错误；没有这项时先核对当前 Cursor 版本和 MCP 设置入口。
Server 根本没有出现在 Customize
- 原因
- 可能文件位置错误、JSON 解析失败、工作区不对，或组织策略阻止用户自定义。
- 怎么改
- 确认根目录 .cursor/mcp.json 与 mcpServers 包装，检查当前打开的工作区和日志解析错误；不要先换远程 Token。
Server 显示连接失败
- 原因
- URL、网络或提供方连接异常；stdio 则可能是程序不存在。
- 怎么改
- 按传输检查日志。公开 Docs URL 不应要求自带 API Key；若返回网页或代理错误，先确认错误来自谁。
工具存在，但对话始终直接回答
- 原因
- 相关性判断、禁用状态或 Run Mode/审批可能让调用未发生。
- 怎么改
- 明确指定 Server 与问题，展开调用记录并检查是否已启用；不要把流畅回答视为 MCP 成功。
HTTP 配置里的 envFile 不生效
- 原因
- 这个字段只用于 stdio。
- 怎么改
- 依据提供方选择 OAuth 或受支持的 headers 环境变量插值，再检查启动 Cursor 的环境；不把密钥硬编码进可共享配置。
连接成功，业务工具返回 403
- 原因
- 协议连接与业务资源授权不同，连接不授予额外资源权限。
- 怎么改
- 核对业务账号、目标资源及授权范围，用同一输入复测；不要通过把项目配置搬到全局来处理。
先停用确认消失，再按来源清理
临时排错可在 Customize 中关闭本例 Server，观察它不再参与新对话工具调用。永久移除则从它实际来源的 mcp.json 删除对应条目并重载，再核对全局/插件/团队是否还有同一连接。不要删除整个配置文件来卸载一项服务。
公开文档主线没有提供方账号授权。若你接的是个人 SaaS，Cursor 端删除连接与提供方撤权分开处理；退出工作区、关闭开关或清理 JSON，不能证明远程访问令牌已失效。
资料与核对范围
资料核对日：2026-10-10。以下来源支持协议与配置说明；文中的命令、练习和预期结果不代表本站已在所有客户端和系统完成实测。