MCP 让 Agent 调用外部工具与数据源。在桌面端，MCP 通过侧栏 能力 管理（「连接」分组、推荐项，以及 添加能力 → 手动添加 MCP）。设置页侧栏不再单独挂载 MCP 页签。
配置文件：~/.astravia/agent/mcp.json（全局）。OAuth 凭证可能额外保存在 ~/.astravia/agent/mcp-auth/。
全局 MCP 连接会在应用启动后预热并跨会话复用。项目 .astravia/mcp.json 中的连接、引用 ${PROJECT_ROOT} 的全局连接，以及设置了 "resourceScope": "workspace" 的全局连接仍按工作区隔离，并可使用当前工作区的 MCP roots。依赖 roots/list、但配置文本里没有 ${PROJECT_ROOT} 的全局连接，应在高级 JSON 配置中显式设置 resourceScope 为 workspace。
添加推荐 / 发现中的 MCP
发现列表中的推荐连接器来自内置预设与市场数据。当前代码中标记为可在发现列表展示的内置示例包括（以你安装的客户端版本为准）：
- Notion（远程 HTTP，浏览器 OAuth）
- Figma（stdio + API Key）
- GitHub（远程 HTTP + Personal Access Token）
其它预设可能已内置匹配逻辑但未在发现列表展示。
选择连接器
在 能力 → 发现 中打开 MCP 详情。
完成凭证或授权
按提示填写密钥，或完成浏览器授权 / 设备码流程。未完成配置前状态为 需配置。
在会话中验证
保存并启用后，在对话中让 Agent 列出或调用相关工具。
手动添加 MCP
添加能力 → 手动添加 MCP，传输类型：
本地进程：填写 命令、参数，可选环境变量与工作目录。
配置落盘形态示例（键名即服务名）：
{
"mcpServers": {
"my-tools": {
"command": "node",
"args": ["./tools/server.mjs"],
"env": {
"TOKEN": "..."
}
}
}
}自动批准与排错
- 自动批准工具：手动/高级配置中可按工具名（逗号分隔）写入自动批准列表，跳过对应工具的逐次确认。只应对行为可预测、输入范围受控的工具启用。
- 连接失败时检查：命令是否可执行、工作目录、环境变量、HTTP URL、认证状态、启动超时。
- 可对已添加项 编辑配置、连接账户 / 断开账户（OAuth）、停用 或 移除。
第一次验证连接时先使用只读工具，并让 Agent 报告它实际看到的工具名和结果：
PLATE 01
MCP 最小验证先列出当前会话中来自 [连接器名称] 的可用工具，不执行任何写操作。
选择一个只读工具做最小调用，并报告工具名、关键参数和结果摘要。
如果没有发现工具、需要额外授权或只有写入工具，请停止并说明当前连接状态。连接成功不等于每个工具都应自动批准。确认工具行为、参数范围和数据边界后，再考虑对稳定的只读调用启用自动批准。