#MCP 集成

Model Context Protocol（MCP） 让 Cursor 接到外部工具和数据，而不必每次把项目结构讲一遍。从 Customize 安装，或手写 mcp.json。协议、传输与安全的完整课见本站 MCP 教程；本章只讲 Cursor 里怎么配、怎么用。权威页：cursor.com/docs/mcp。

#为什么要在 Cursor 里用 MCP

没有 MCP 时，你只能把 issue、设计稿、数据库 schema 粘进聊天。有 MCP 后，Agent（含 Plan Mode）可以在 Available Tools 里直接调这些能力。用任何能写 stdout 或提供 HTTP 端点的语言都能写服务器。

官方插件：Cursor Marketplace（Customize 里一键安装，常走 OAuth）。社区目录：cursor.directory。企业还可以从团队市场分发。

#传输方式

Cursor 还支持 Tools、Prompts、Resources、Roots、Elicitation，以及可返回交互 UI 的 MCP Apps（宿主不能渲染 UI 时，普通 MCP 响应仍可用）。

#配置文件放哪

CLI 的 agent 共用这些文件。项目 → 全局 → 嵌套发现的优先级与编辑器一致。

#mcp.json 示例

stdio（Node）：

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

stdio（Python）：

{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

远程 HTTP / SSE：

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

stdio 常用字段：type（"stdio"）、command、args、env、envFile（如 "${workspaceFolder}/.env"）。envFile 只适用于 stdio；远程服务器请用环境变量插值。

需要固定 Client ID 的远程 OAuth 时，可在 url 条目上加 auth（CLIENT_ID、可选 CLIENT_SECRET、scopes）。桌面回调为 http://localhost:8787/callback，Web / Cloud Agents 为 https://www.cursor.com/agents/mcp/oauth/callback。细节以官方 MCP 页为准。

#插值

Cursor 会解析这些字段里的变量：command、args、env、url、headers（auth 同样支持）。

不要把密钥写进 JSON。 用 ${env:NAME}，并把 .env 留在 Git 外面。

#在聊天里怎么用、怎么批准

相关时 Agent 会自己选 MCP 工具；你也可以点名或描述需求。在 Customize 里开关服务器。默认会先征求批准——展开工具名可看参数。

MCP 遵循与终端相同的 Run Modes。例如 Auto-review：白名单工具可立即跑，其余走分类器。见 Run Modes。

调试：

1. 打开 Output（Ctrl+Shift+U / Cmd+Shift+U）
2. 下拉选择 MCP Logs
3. 看连接、认证、崩溃

一个服务器挂了不会拖垮其他服务器。

CLI：

agent mcp list
agent mcp list-tools playwright
agent mcp login <identifier>

#安全（先读再装）

官方实践：

• 只装可信作者 / 仓库
• 看清它要访问的数据和 API
• API key 最小权限
• 关键集成先审源码

MCP 能代表你访问外部服务并在本机执行逻辑。敏感数据优先 stdio + 环境变量，不要把 token 写进仓库。企业管理员可配允许名单、网络沙箱和团队市场——以 Dashboard 为准。

协议层的威胁模型、鉴权与客户端实现，请读本站 MCP 教程，不要只停在「能连上」。

#最小验证

1. 在 Customize 或 mcp.json 加一台服务器。
2. 看它出现在 Available Tools。
3. 对 Agent 说：Use the <server> tools to …（换成真实能力）。
4. 展开工具调用，确认参数里没有意外路径或密钥。

#下一步

• 模型选择
• 实战案例
• 本站 MCP 教程