Cursor SDK 中 MCP 服务器的配置与实战:本地/云端双运行时下的 HTTP、stdio 与凭据管理

原创2026-09-15 10:31:491,743 阅读
文章标签:AI 技能AI 插件开发工具代码评审代码质量插件系统

Cursor SDK 中 MCP 服务器的配置与实战:本地/云端双运行时下的 HTTP、stdio 与凭据管理

本篇技术指南围绕 Cursor 官方 SDK(@cursor/sdk)的技能参考文档 mcp.md 展开,系统讲解在本地与云端两种运行时下为 Agent 配置 MCP(Model Context Protocol)服务器的完整方法。你将掌握 McpServerConfig 的完整类型结构、两种传输协议与三种部署形态的取舍、本地与云端在凭据处理上的关键差异、Agent.resume 与 settingSources 的持久化规则,以及一套可直接用于排查“Agent 没有拿到工具”类问题的调试清单。文中的代码示例与结论均以当前仓库中的 SDK 技能文档及其实战参考为事实依据。

MCP 是什么,以及为什么配置错了往往是“静默失败”

MCP(Model Context Protocol)服务器为 Agent 提供额外的工具能力。@cursor/sdk 同时支持本地(local)与云端(cloud)两种运行时,但两种运行时下的传输语义与凭据处理规则截然不同。配置错误通常不会抛出异常,而是表现为一种典型的静默失败——“为什么我的 Agent 没有 Linear 工具?”。因此,理解本文中的每一条差异,都是避免在生产环境中反复踩坑的前提。

SDK 技能主页 SKILL.md 将 MCP 配置归类为“Configuring MCP servers (HTTP, stdio, cloud vs local transport, auth injection)”这一专门场景,并明确要求在此类任务发生时读取 mcp.md 参考文件,说明该文档正是官方技能体系中处理 MCP 配置的权威来源。

两种传输协议,三种部署形态

在动手写配置之前,先理解 MCP 配置的类型骨架。SDK 中的服务器配置统一由 McpServerConfig 表达:

type McpServerConfig =
  | { type?: "stdio"; command: string; args?: string[]; env?: Record<string,string>; cwd?: string }
  | { type?: "http" | "sse"; url: string; headers?: Record<string,string>; auth?: { CLIENT_ID: string; CLIENT_SECRET?: string; scopes?: string[] } };

type 字段是可选的:省略时默认按对应分支推断(带 command 视为 stdio,带 url 视为 HTTP/SSE)。实际使用中你会遇到三种部署形态:

  1. 本地 stdio —— 在调用方机器上拉起一个子进程。这是大多数 @modelcontextprotocol/server-* 官方包的默认形态,例如文件系统、GitHub 等本地优先的辅助工具。
  2. 本地 HTTP / 远程 HTTP —— 提供一个 URL,由 SDK(本地运行时)或 Cursor 后端(云端运行时)代表 Agent 去调用。
  3. 云端 stdio —— 子进程在云端 VM 内部启动,而不是在调用方机器上。

两种运行时下配置的形状看起来几乎一样,真正变化的是执行位置。一个值得记住的具体差异是:云端 stdio 服务器拒绝 cwd 字段——VM 自己控制工作目录,如果你尝试设置,会抛出 ConfigurationError("Cloud MCP server cannot include cwd.")。云端 stdio 配置中请务必省略 cwd。

从运行时决策参考 runtime-choice.md 的能力矩阵可以看到,MCP 的 stdio 与 HTTP 两种传输在本地和云端均受支持,但 stdio 在云端意味着命令在云端 VM 中执行,这直接影响了后续的凭据安全策略。

本地运行时:MCP 配置

本地运行时下,MCP 服务器作为你的 Node 进程的子进程或由 SDK 直接发起 HTTP 调用。完整示例:

const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  mcpServers: {
    filesystem: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
      cwd: process.cwd(),
      env: { NODE_OPTIONS: "--max-old-space-size=4096" },
    },
    docs: {
      type: "http",
      url: "https://example.com/mcp",
      headers: { Authorization: `Bearer ${process.env.DOCS_TOKEN!}` },
    },
  },
});

配置要点:

  • stdio 服务器是 Node 进程的子进程。确保 command 位于 PATH 中,或使用绝对路径;示例中通过 npx -y 按需拉取官方包,通过 env 注入 NODE_OPTIONS 控制内存上限,通过 cwd 指定工作目录。记得在结束时干净地释放 Agent(agent[Symbol.asyncDispose]() 或 await using),以回收这些子进程。
  • HTTP 服务器由本地 SDK 直接调用,headers 会附加到每一个请求上。
  • auth: { CLIENT_ID, CLIENT_SECRET?, scopes? } 会触发 OAuth 流程,适用于能够签发正规 OAuth 令牌的一方集成(first-party integrations)。大多数自托管的 MCP 服务器只需要 headers 就够了。

值得注意的是,本地运行时的 stdio 服务器运行在调用方机器上、以调用方的权限执行工具。这与运行时选择文档 runtime-choice.md 中的提醒一致:要把本地 Agent 当作 rm -rf 级别的工具对待,注意作用域 cwd,不要在环境变量中放你不希望暴露的密钥。

云端运行时:MCP 配置与凭据安全的关键差异

云端运行时下,Agent 运行在 Cursor 托管的 VM 中,针对克隆的仓库执行。完整示例:

const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: {
    repos: [{ url: "https://github.com/your-org/your-repo", startingRef: "main" }],
  },
  mcpServers: {
    linear: {
      type: "http",
      url: "https://mcp.linear.app/sse",
      headers: { Authorization: `Bearer ${process.env.LINEAR_API_KEY!}` },
    },
    github: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
    },
  },
});

与本地相比,有三条关键差异,直接决定你的凭据是否安全:

  • HTTP 的 headers 与 auth 由 Cursor 后端代理转发。 敏感的 header 值会在服务端被脱敏(redacted),不会进入云端 VM。这是存放 OAuth 令牌、API 密钥等敏感信息的安全位置。
  • stdio 的 env 值会被注入到云端 VM。 必须像对待任何生产密钥一样对待它们——VM 内运行的进程都能看到这些值。不要把终端用户的凭据通过这种方式下发。
  • command/args 必须在云端 VM 内可解析。 云端 VM 是标准 Linux 镜像,npx、node 和常见二进制可用;其他工具需要确保 command 在 VM 中可解析,或者由容器提供对应二进制。

另外,通过 Cursor 控制台(https://cursor.com/agents)配置的 MCP 服务器在云端同样生效。用户只需在控制台配置一次,Agent.create 上的内联配置会叠加在其之上。

关于云端运行时的其他行为,可参见 runtime-choice.md:云端 Agent ID 以 bc- 前缀标识,SDK 辅助方法会据此自动路由;调用方(CURSOR_API_KEY 背后的用户)必须对目标仓库建立 GitHub 连接,否则云端会返回 ERROR_GITHUB_NO_USER_CREDENTIALS——这是环境配置问题,不是代码缺陷。

跨 Agent.resume(...) 的持久化:内联配置不会保留

内联的 mcpServers 不会被持久化。 如果你恢复(resume)一个 Agent 并期望它拥有相同的 MCP 工具访问权,必须再次传入配置:

const baseMcp = { /* ... */ };
const agent = Agent.resume(agentId, {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  mcpServers: baseMcp,
});

控制台(dashboard)配置的服务器则会持久化——因为它们绑定的是用户而不是 Agent。因此一个常见的错误模式是:贪图内联配置的便利,然后在 resume 时发现工具丢了。

高级参考 advanced.md 对“什么会持久化 / 什么不会持久化”给出了更完整的边界:

  • 会持久化:对话历史与 Agent 状态、创建时服务端烘焙的 Agent 级设置;云端还包括整个 Agent(克隆、分支、PR 状态)。
  • 不会持久化:内联 mcpServers(必须重新传入);本地的 cwd(按路径识别,路径消失则找不到 Agent);local.settingSources(环境配置基于当前环境重新加载)。

该文档中的长生命周期服务示例正是这一规则的工程化落地——把 MCP 配置抽成一个 options 对象,每次 Agent.create / Agent.resume 都重新传入,确保 resume 后工具不丢。

由 Settings 来源加载 MCP:settingSources 与作用域规则

默认情况下,本地 SDK Agent 不会加载用户/团队/项目级别的环境 MCP 配置。需要显式通过 settingSources 选择加入:

const agent = Agent.create({
  apiKey,
  model: { id: "composer-2" },
  local: {
    cwd: process.cwd(),
    settingSources: ["project", "user"], // or "all"
  },
});

三个容易踩的规则:

  • settingSources 位于 local 内部——放在顶层会导致 TypeScript 编译失败,在 JavaScript 中则静默无效。
  • 它对云端 Agent 没有效果;云端始终尊重 project / team / plugins。
  • 合法取值:"project"、"user"、"team"、"mdm"、"plugins",或 "all" 包含全部。使用能满足需求的最窄集合——"all" 可能把团队策略和插件带入生产代码,带来意外。

内联 mcpServers 始终优先:它们是显式输入,而非环境配置。两者可以组合使用。

SKILL.md 的生产最佳实践也与此呼应:除非确实需要环境配置,否则保持 local: { settingSources: [] }(默认值);对云端 Agent 而言该字段无效果。

HTTP 与 stdio 的选型决策

对于远程服务(Linear、GitHub、Jira、Figma、你自己的内部工具),选型原则如下:

  • 优先 HTTP:当服务有稳定的 MCP 端点时。云端场景下 Cursor 后端负责代理鉴权,你无需把密钥送入 VM。
  • 使用 stdio:当集成对象是本地优先的辅助工具(文件系统、CLI、开发工具)时,或者你需要进程级隔离时。云端场景下 stdio 服务器运行在 Cursor VM 内——对无状态辅助工具没问题,但对持有长期凭据的进程是危险的。
  • 对于支持 OAuth 的一方 MCP 服务器,优先使用 auth: { CLIENT_ID, CLIENT_SECRET?, scopes? },而不是硬编码 Authorization header。

这一定位与 runtime-choice.md 的整体选型逻辑一致:本地适合开发循环、已检出仓库的 CI 步骤、无需网络克隆的快速迭代;云端适合需要开 PR、需要比调用方进程活得更久、需要隔离计算资源的场景。

文件变更后重载 MCP:agent.reload()

如果你在 Agent 运行期间修改了本地磁盘上的 .cursor/mcp.json 或其他设置来源,并且希望 Agent 在不重建的情况下重新加载:

await agent.reload();

注意:reload() 只影响未来的 send() 调用;正在执行中的运行仍然使用它们启动时的配置。

advanced.md 进一步说明:在修改本地设置(.cursor/*、MCP 配置文件、hook 文件)之后调用 agent.reload(),可以让底层本地执行器在不重建 Agent 的前提下拾取变更。

调试 MCP 故障的清单

MCP 配置问题往往表现为“Agent 没有这个工具”,而不是抛出错误。按以下清单逐项排查:

  1. 服务器真的注册了吗? 在流开始处观察 system 事件——它有时会包含工具目录(tool catalog)。如果没有,说明服务器没有接上。
  2. 云端 stdio 的命令可用吗? command 是否在云端 VM 镜像中可用?npx 可用,但你的自定义 /usr/local/bin/… 不可用。
  3. HTTP headers 缺失? 云端场景下敏感 header 会被脱敏但仍然会转发;header 缺失说明 SDK 配置里没有包含它们。检查拼写——某些服务器要求 Authorization 而不是 authorization。
  4. resume 时没有重新传入 MCP? 你丢失了内联服务器。在 resume 选项中重新传入。
  5. settingSources 没设置? Agent 没有加载你项目的 .cursor/mcp.json。加上 "project"。

若故障最终表现为运行失败而非配置问题,可参考 error-handling.md 的二维错误模型:CursorAgentError 抛出表示运行根本没启动(鉴权、配置、网络问题),result.status === "error" 表示 Agent 执行了工作但工作失败——两种情况的修复方式与可重试性完全不同。

开箱即用的复制粘贴起步配置

以下是四种最常见的 MCP 起步配置,可直接复制使用。

本地文件系统辅助工具

mcpServers: {
  filesystem: {
    type: "stdio",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
  },
},

云端 + Linear(HTTP,云端代理鉴权)

mcpServers: {
  linear: {
    type: "http",
    url: "https://mcp.linear.app/sse",
    headers: { Authorization: `Bearer ${process.env.LINEAR_API_KEY!}` },
  },
},

云端 + GitHub(stdio,密钥注入 VM)

mcpServers: {
  github: {
    type: "stdio",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"],
    env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
  },
},

Cursor 控制台配置的服务器(无需内联配置)

只要云端 Agent 被允许使用团队 MCP,用户在控制台配置好的服务器即可直接生效,无需任何内联配置;仅在你还想叠加额外服务器时才需要内联。

综合示例:把 MCP 配置嵌入真实集成

将上述知识点串起来,参考 patterns.md 中的定时分诊(scheduled triage)模式:一个每天早晨恢复昨日分诊 Agent、请求它处理今日新增 Linear 工单的 cron 任务。其核心是把 MCP 配置抽成常量并在每次 create/resume 时重新传入:

const mcpServers = {
  linear: {
    type: "http" as const,
    url: "https://mcp.linear.app/sse",
    headers: { Authorization: `Bearer ${process.env.LINEAR_API_KEY!}` },
  },
};

await using agent = state.agentId
  ? Agent.resume(state.agentId, {
      apiKey: process.env.CURSOR_API_KEY!,
      model: { id: "composer-2" },
      cloud: { repos: [{ url: process.env.REPO_URL!, startingRef: "main" }] },
      mcpServers, // resume 时必须重新传入
    })
  : Agent.create({
      apiKey: process.env.CURSOR_API_KEY!,
      model: { id: "composer-2" },
      cloud: { repos: [{ url: process.env.REPO_URL!, startingRef: "main" }] },
      mcpServers,
    });

该模式同时示范了:patterns.md 中“持久化 agentId 跨 cron 调用以保留对话记忆”“每次 resume 重新传入 MCP 配置”“对可重试错误优雅跳过本轮”等生产实践。另一个典型场景是 GitHub Action 代码审查机器人——它按需条件性地注入 GitHub 的 stdio MCP 服务器(mcpServers: GITHUB_TOKEN ? { github: {...} } : undefined),展示了如何根据环境变量存在与否灵活组装 MCP 配置。

小结

MCP 服务器配置是 Cursor SDK 集成中最容易“静默失败”的环节。核心要点可归纳为:先分清本地与云端执行位置,再选择 HTTP 或 stdio 传输,最后严格区分凭据的存放位置——云端 HTTP 的 header/auth 由后端代理并脱敏,是敏感凭据的安全位置;云端 stdio 的 env 会暴露给 VM 内所有进程,只适合无状态辅助工具。同时牢记两条持久化规则:内联 mcpServers 在 resume 时不保留(必须重传),settingSources 只作用于本地且位于 local 内部。把这些规则融入 SKILL.md 提供的三大约定调用模式(Agent.prompt、Agent.create + send、Agent.resume)之中,你就能构建出既安全又可长期稳定运行的 Cursor Agent 集成。

登录后查看全文
plugins