Cursor SDK 中 MCP 服务器的配置与实战:本地/云端双运行时下的 HTTP、stdio 与凭据管理
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)。实际使用中你会遇到三种部署形态:
- 本地 stdio —— 在调用方机器上拉起一个子进程。这是大多数
@modelcontextprotocol/server-*官方包的默认形态,例如文件系统、GitHub 等本地优先的辅助工具。 - 本地 HTTP / 远程 HTTP —— 提供一个 URL,由 SDK(本地运行时)或 Cursor 后端(云端运行时)代表 Agent 去调用。
- 云端 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? },而不是硬编码Authorizationheader。
这一定位与 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 没有这个工具”,而不是抛出错误。按以下清单逐项排查:
- 服务器真的注册了吗? 在流开始处观察
system事件——它有时会包含工具目录(tool catalog)。如果没有,说明服务器没有接上。 - 云端 stdio 的命令可用吗?
command是否在云端 VM 镜像中可用?npx可用,但你的自定义/usr/local/bin/…不可用。 - HTTP headers 缺失? 云端场景下敏感 header 会被脱敏但仍然会转发;header 缺失说明 SDK 配置里没有包含它们。检查拼写——某些服务器要求
Authorization而不是authorization。 - resume 时没有重新传入 MCP? 你丢失了内联服务器。在 resume 选项中重新传入。
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 集成。