企业官网建设流程全解析

MCP 从 0 接入 Cursor：mcp.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 与风险面。

结论卡

背景与边界

MCP（Model Context Protocol）让 IDE 里的模型按统一协议发现并调用外部工具。Cursor 可从 Marketplace 一键装，也可手写 JSON。手写的好处是可进 Git、可 Code Review。

边界：包名必须以该 MCP 维护者文档为准，不要从目录「标题」脑补 npm 包；OAuth 类远程服务以厂商回调为准。Windows 路径与 macOS/Linux 的npx可用性可能不同，下文以常见 Unix 开发机为例。

原理

一次成功调用大致经过：

1. Cursor 读取合并后的mcpServers；
2. 对 STDIO：spawncommand，做 MCP handshake，缓存工具列表；
3. 对远程：按url建连，必要时带headers/ OAuth；
4. Agent 需要时加载完整 schema（官方已做动态上下文），发起 tool call；
5. 结果回灌对话——超长 JSON 会继续占 Token。

注意：面板绿灯只说明进程/连接活着，不代表鉴权 scope 足够，也不代表你该把写操作默认打开。

步骤 + 代码

步骤 1：选落点并创建文件

目的：让 Cursor 读到你的服务器定义。

mkdir-p.cursortouch.cursor/mcp.json

全局（所有项目可见）：

mkdir-p~/.cursortouch~/.cursor/mcp.json

易错点

1. 把文件建在仓库根的mcp.json（少了.cursor/）；
2. 项目与全局同名服务器时，不清楚谁生效（项目优先）；
3. 用了错误的顶层键名（必须是mcpServers）。

步骤 2：写入最小 STDIO 示例

目的：用官方常见的 GitHub MCP 形态演示字段；请把包名替换成你文档中的真实包。

{"mcpServers":{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"${env:GITHUB_TOKEN}"}}}}

先在 shell 导出（勿写进 JSON）：

exportGITHUB_TOKEN="ghp_your_readonly_or_minimal_scope_token"

远程 URL 形态（示例结构，endpoint 以厂商为准）：

{"mcpServers":{"notion":{"url":"https://mcp.notion.com/mcp","headers":{"Authorization":"Bearer ${env:NOTION_TOKEN}"}}}}

易错点

1. JSON 末尾多余逗号导致静默加载失败；
2. 本机没有npx/Node，STDIO 进程秒退；
3. 把url与command写在同一 server 里混用字段。

步骤 3：重载并确认绿灯

目的：让新配置进入运行时。

1. 保存mcp.json；
2. Command Palette →Reload Window（或完全退出再开）；
3. 打开 Settings →MCP，确认目标服务器为已连接；
4. 若红灯，点进查看日志（常见：command not found、鉴权 401、JSON parse）。

步骤 4：最小只读调用

目的：用低风险任务证明「工具真的被 Agent 用到」。

在Ask或受限 Agent 中发送：

请列出当前已加载的 MCP 服务器与可用工具名。 然后只用只读能力：查询我指定仓库的最近 3 条 open issues 标题（仓库：ORG/REPO）。 不要创建、评论或关闭任何 issue。

若模型乱用写接口，立刻停，检查 Token scope 与提示词边界。

易错点

1. 一上来就让 Agent「帮我把所有 issue 关了」；
2. 验证失败时不停换包名，却从未看 MCP 日志；
3. 同一对话堆积超长 API 响应还不新开线程（Token 爆炸）。

步骤 5：项目级与全局合并时的协作约定

目的：避免「我机器绿灯、同事红灯」和密钥进库。

推荐约定：

1. 仓库只提交无密钥的.cursor/mcp.json模板；
2. 每人用 shell 环境变量或本地未跟踪的覆盖文件提供 Token；
3. README 写清：需要哪些 env、最小 scope、如何 Reload；
4. CI 若不用 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 工具名（验证用）

易错点

1. example 与真实文件同名，新人直接提交密钥；
2. 文档写「安装扩展」但 Cursor 实际吃的是mcp.json；
3. 公司代理下npx首次下载失败却误判为 MCP 协议坏了。

步骤 6：本地 STDIO 排障命令

目的：在 Cursor 外先确认 command 能跑，缩小「是 IDE 问题还是进程问题」。

node-v&&npx-vnpx-y@modelcontextprotocol/server-github

若手动都起不来，先修 Node/权限/网络，再回 Cursor 面板。

易错点

1. 在 Cursor 日志里空转半小时，从未在终端复现；
2. 手动试跑时把 Token 打在 shell 历史明文里；
3. 杀掉进程不干净，端口/子进程残留导致「好像连着」。

步骤 7：最小权限 Token 清单

目的：验证阶段只用只读 scope，降低 MCP 被误用的爆破半径。

风险：MCP 一旦挂上可写工具，Ask/Agent 选错模式就会放大事故——敏感仓库先断写工具。

步骤 8：和 Ask/Agent 一起用的安全默认

目的：MCP 点亮后，用模式选择避免「工具已加载 = 可以随便写」。

1. 第一次验证固定走Ask或明确「只读」的 Agent 提示；
2. 需要写 Issue/开 PR 时，单独开对话并写进任务书；
3. 做完立刻在 MCP 面板断开可写服务器，或从mcp.json临时移除；
4. 对照同日《Ask vs Agent vs Manual》决策表，敏感动作升级为 Manual。

结论：MCP 解决的是「够不够得到工具」，模式解决的是「该不该自动用」。

验证

可选：用python -m json.tool < .cursor/mcp.json本地校验语法。

python3-mjson.tool .cursor/mcp.json>/dev/null&&echoOK

易错点：校验的是语法不是语义——包名错了 JSON 仍 OK。

踩坑（常见报错对照）

风险：给 MCP Token 的 scope 应小于等于任务需要；只读验证阶段不要用管理特权 Token。

下一步

• 只保留1个与本周任务相关的 MCP，其余断开
• 把示例mcp.json（无密钥）提交仓库，在 README 写清所需环境变量名
• 结合同日《省 Token》文，检查工具结果是否在同一线程无限回灌
• 需要模式分流时，读《Ask vs Agent vs Manual》

注意：具体包名、Settings 菜单文案随 Cursor 版本可能微调；以你安装版本的官方 MCP 文档为准。本稿为草稿，勿直接发布过期包名而不复核。