SDK 配置与扩展

SDK 同时支持 inline 选项和文件配置。不要把编辑器已启用的全部设置视为本地 SDK 的默认输入；用 local.settingSources 明确选取需要的层。

设置来源

local.settingSources 可包含 project、user、team、mdm、plugins 或 all，分别对应 workspace .cursor、用户 ~/.cursor、团队、MDM 和插件配置。云端忽略该选项，始终加载 project/team/plugins。

本地 MCP 同名优先级为每轮 inline、创建时 inline、插件、项目、用户；只有选择对应 settingSources 才加载磁盘或插件来源。未提供 settingSources 时只加载 inline MCP。每轮定义替代创建定义，不合并。

云端 MCP 依次使用每轮 inline、创建时 inline、网页配置的用户/团队 servers。个人 key 的 inline server 未带 auth/headers 且此前在网页授权过相同 URL 时可复用 OAuth；服务账号不能回退使用个人授权。

MCP 凭据与恢复

HTTP headers/auth 由 Cursor 后端处理，敏感字段不进 VM；stdio env 会进入运行 server 的 VM。stdio cwd 仅适用于本地，云端拒绝该字段。传输支持差异见创建 API中的官方 SSE 冲突说明。

本地 SDK 无法交互发起 MCP OAuth 登录，只能复用先前通过 Cursor App 获得的登录。inline mcpServers 不跨 resume 持久化，恢复时重传或改用带 settingSources 的文件配置。

Subagents

创建时 agents 提供命名定义，每项必填 description/prompt，model 默认 inherit。项目 .cursor/agents/*.md 也会加载，inline 同名定义覆盖文件。主 Agent 和直接 subagent 能继续派生，第二层 subagent 不能再派生。

AgentDefinition.mcpServers 当前仅前向兼容：字符串引用被忽略，inline 配置抛 ConfigurationError；subagent 继承父 MCP。不要把类型中出现字段理解为已经支持独立 MCP 范围。

Custom tools

本地 local.customTools 会注册为 custom-user-tools MCP server，并传给含嵌套层的 subagents。创建时设置适用后续轮，send 中设置只替换当前轮。云端创建会忽略 local.customTools，send 时提供则抛 ConfigurationError。

每个工具的 execute 接收已解析 args 和含 toolCallId/sessionId 的 context，每个 subagent 有自己的 sessionId。可返回字符串、JSON，或 content/isError/structuredContent envelope；抛异常也作为工具错误反馈。

inputSchema 默认允许任意属性，description 默认空字符串。outputSchema 用于向模型声明结果形状，不验证返回数据；readOnlyHint、destructiveHint 等 annotations 只是描述提示，不自动执行访问控制。execute 在宿主进程运行，权限等同应用代码可访问范围。

Hooks 与重新加载

Hooks 只来自文件，没有程序化 callback。把 .cursor/hooks.json 和脚本放进本地 cwd 或提交到云端仓库；本地还可使用 ~/.cursor/hooks.json。Enterprise 云端还运行团队与企业管理 Hooks。

agent.reload() 重新读取 Hooks、project MCP 和 subagents，不必销毁 Agent。事件和失败规则见Hooks 配置。