MCP 从 0 接入 Cursormcp.json 安装配置到最小调用与常见报错想让 Cursor Agent「去 GitHub 查 Issue」「读你们内部文档库」却卡在MCP 面板一直红灯、改完 JSON 没变化、Token 写进仓库又心虚。工具协议本身不复杂复杂的是配置落点、重载时机、密钥不进 Git这三件事没对齐。本文按从 0 路径走完安装位置 → 最小配置 → 一次只读调用 → 验证 → 踩坑。读完你应能在项目里点亮1个 MCP并知道红灯时先查哪四层。不讲自造服务器源码重点是 Cursor 侧接入。摘要Cursor 通过mcpServers拉起本地 STDIO 进程或连接远程 HTTP/SSE。项目级用.cursor/mcp.json全局用~/.cursor/mcp.json同名时项目覆盖全局。改配置后需 Reload Window 或重启密钥用${env:NAME}。先做只读任务验证再开放写权限。结论先绿灯、再最小调用、最后扩权限把 MCP 当收藏夹会同时抬高 Token 与风险面。结论卡项推荐做法配置文件团队共享 → 项目.cursor/mcp.json个人复用 →~/.cursor/mcp.json传输本地包 →commandargs托管服务 →url 可选headers密钥${env:GITHUB_TOKEN}等禁止明文提交验证Settings → MCP 显示已连接 Agent 能列出工具并完成只读任务省 Token当天不用的服务器断开或删条目见同日 Token 实战背景与边界MCPModel Context Protocol让 IDE 里的模型按统一协议发现并调用外部工具。Cursor 可从 Marketplace 一键装也可手写 JSON。手写的好处是可进 Git、可 Code Review。边界包名必须以该 MCP 维护者文档为准不要从目录「标题」脑补 npm 包OAuth 类远程服务以厂商回调为准。Windows 路径与 macOS/Linux 的npx可用性可能不同下文以常见 Unix 开发机为例。原理一次成功调用大致经过Cursor 读取合并后的mcpServers对 STDIOspawncommand做 MCP handshake缓存工具列表对远程按url建连必要时带headers/ OAuthAgent 需要时加载完整 schema官方已做动态上下文发起 tool call结果回灌对话——超长 JSON 会继续占 Token。注意面板绿灯只说明进程/连接活着不代表鉴权 scope 足够也不代表你该把写操作默认打开。步骤 代码步骤 1选落点并创建文件目的让 Cursor 读到你的服务器定义。mkdir-p.cursortouch.cursor/mcp.json全局所有项目可见mkdir-p~/.cursortouch~/.cursor/mcp.json易错点把文件建在仓库根的mcp.json少了.cursor/项目与全局同名服务器时不清楚谁生效项目优先用了错误的顶层键名必须是mcpServers。步骤 2写入最小 STDIO 示例目的用官方常见的 GitHub MCP 形态演示字段请把包名替换成你文档中的真实包。{mcpServers:{github:{command:npx,args:[-y,modelcontextprotocol/server-github],env:{GITHUB_PERSONAL_ACCESS_TOKEN:${env:GITHUB_TOKEN}}}}}先在 shell 导出勿写进 JSONexportGITHUB_TOKENghp_your_readonly_or_minimal_scope_token远程 URL 形态示例结构endpoint 以厂商为准{mcpServers:{notion:{url:https://mcp.notion.com/mcp,headers:{Authorization:Bearer ${env:NOTION_TOKEN}}}}}易错点JSON 末尾多余逗号导致静默加载失败本机没有npx/NodeSTDIO 进程秒退把url与command写在同一 server 里混用字段。步骤 3重载并确认绿灯目的让新配置进入运行时。保存mcp.jsonCommand Palette →Reload Window或完全退出再开打开 Settings →MCP确认目标服务器为已连接若红灯点进查看日志常见command not found、鉴权 401、JSON parse。步骤 4最小只读调用目的用低风险任务证明「工具真的被 Agent 用到」。在Ask或受限 Agent 中发送请列出当前已加载的 MCP 服务器与可用工具名。 然后只用只读能力查询我指定仓库的最近 3 条 open issues 标题仓库ORG/REPO。 不要创建、评论或关闭任何 issue。若模型乱用写接口立刻停检查 Token scope 与提示词边界。易错点一上来就让 Agent「帮我把所有 issue 关了」验证失败时不停换包名却从未看 MCP 日志同一对话堆积超长 API 响应还不新开线程Token 爆炸。步骤 5项目级与全局合并时的协作约定目的避免「我机器绿灯、同事红灯」和密钥进库。推荐约定仓库只提交无密钥的.cursor/mcp.json模板每人用 shell 环境变量或本地未跟踪的覆盖文件提供 TokenREADME 写清需要哪些 env、最小 scope、如何 ReloadCI 若不用 MCP不要在 CI 镜像里强行装同一套服务器。!-- 可放进 README 的片段 -- ## Cursor MCP 1. cp .cursor/mcp.json.example .cursor/mcp.json若你们拆了 example 2. export GITHUB_TOKEN...classic/fine-grained 均可建议只读 3. Cursor: Reload Window → Settings → MCP 见绿灯 4. 用 Ask 发送请列出 MCP 工具名验证用易错点example 与真实文件同名新人直接提交密钥文档写「安装扩展」但 Cursor 实际吃的是mcp.json公司代理下npx首次下载失败却误判为 MCP 协议坏了。步骤 6本地 STDIO 排障命令目的在 Cursor 外先确认 command 能跑缩小「是 IDE 问题还是进程问题」。node-vnpx-vnpx-ymodelcontextprotocol/server-github若手动都起不来先修 Node/权限/网络再回 Cursor 面板。易错点在 Cursor 日志里空转半小时从未在终端复现手动试跑时把 Token 打在 shell 历史明文里杀掉进程不干净端口/子进程残留导致「好像连着」。步骤 7最小权限 Token 清单目的验证阶段只用只读 scope降低 MCP 被误用的爆破半径。场景Token 建议列 Issue / 读 PR只读contents/issues或等效 fine-grained评论 PR明确加 comment 权限仍禁止 admin任何删仓库/改权限不要给 Agent 用的 Token风险MCP 一旦挂上可写工具Ask/Agent 选错模式就会放大事故——敏感仓库先断写工具。步骤 8和 Ask/Agent 一起用的安全默认目的MCP 点亮后用模式选择避免「工具已加载 可以随便写」。第一次验证固定走Ask或明确「只读」的 Agent 提示需要写 Issue/开 PR 时单独开对话并写进任务书做完立刻在 MCP 面板断开可写服务器或从mcp.json临时移除对照同日《Ask vs Agent vs Manual》决策表敏感动作升级为 Manual。结论MCP 解决的是「够不够得到工具」模式解决的是「该不该自动用」。验证步骤通过标准文件位置.cursor/mcp.json或~/.cursor/mcp.json存在且 JSON 合法面板目标服务器绿灯/Connected发现Agent 能说出工具名调用只读任务返回预期数据安全仓库中无明文 Token.gitignore已忽略本地覆盖文件若有可选用python -m json.tool .cursor/mcp.json本地校验语法。python3-mjson.tool .cursor/mcp.json/dev/nullechoOK易错点校验的是语法不是语义——包名错了 JSON 仍 OK。踩坑常见报错对照现象优先排查改完没变化未 Reload / 未杀干净旧进程改错了全局/项目文件服务器不出现顶层键不是mcpServersJSON 坏了红灯秒退command不在 PATHNode/Python 版本args 包名错误401 / 鉴权失败env 未传入 Cursor 进程OAuth 未完成Token scope 不足工具列表空握手未完成远程 URL 路径错公司代理拦截很费 Token挂太多服务器工具结果刷屏——断开不用的新开对话风险给 MCP Token 的 scope 应小于等于任务需要只读验证阶段不要用管理特权 Token。下一步只保留1个与本周任务相关的 MCP其余断开把示例mcp.json无密钥提交仓库在 README 写清所需环境变量名结合同日《省 Token》文检查工具结果是否在同一线程无限回灌需要模式分流时读《Ask vs Agent vs Manual》注意具体包名、Settings 菜单文案随 Cursor 版本可能微调以你安装版本的官方 MCP 文档为准。本稿为草稿勿直接发布过期包名而不复核。