跳到主要内容
文档导航

MCP 指南

本指南解释 MCP 是什么、Deskmate 如何连接 MCP server、如何按 Agent 启用，以及如何排查连接问题。目标是帮助你理解 MCP 的价值和风险，并以最小化、可审查的方式把外部能力接入 Agent。

MCP 是什么

MCP（Model Context Protocol）是一种把外部工具和数据源连接给 AI Agent 的协议。通过 MCP，Agent 可以访问 GitHub、数据库、文件服务、浏览器、知识库或内部系统等能力。

它的工作方式可以拆成几步：

  • MCP server 提供工具。
  • Deskmate 连接 server。
  • Agent 每轮根据配置获得可用工具目录。
  • 工具调用结果会进入模型上下文。

换句话说，MCP server 是能力来源，Deskmate 负责连接和管理，而每个 Agent 看到哪些工具由你的配置决定。

什么时候需要 MCP

适合使用 MCP 的场景：

  • Agent 需要访问外部 SaaS。
  • Agent 需要操作 GitHub / issue / PR。
  • Agent 需要查询数据库或知识库。
  • Agent 需要连接团队内部系统。
  • 需要复用已有 MCP server 能力。

通常不需要 MCP 的场景：

  • 只做普通聊天。
  • 只读取本地文件。
  • 只运行本地 shell。
  • 第一次试用 Deskmate。

如果你的任务只涉及本地文件或本地 shell，先看本地工具即可，不必引入 MCP。

添加 server

按以下步骤添加一个 MCP server：

  1. 打开 Settings → MCP。
  2. 点击 Add Server。
  3. 填写 server 名称和启动/连接配置。
  4. 如需要环境变量，按提示填写。
  5. 保存后连接 server。
  6. 查看 server 状态和工具列表。

添加时请注意：

  • server 名称应清晰，便于 Agent 配置。
  • 环境变量可能包含敏感信息。
  • 只添加可信来源 server。

授权和连接状态

连接后，server 可能处于以下状态：

状态 含义
Connected 已连接，可列出工具。
Disconnected 未连接。
Auth required 需要授权。
Error 启动或连接失败。

对于需要授权的 server，OAuth 流程大致如下：

  1. Server 请求授权。
  2. Deskmate 弹出授权确认或浏览器登录。
  3. 用户确认范围。
  4. Token 保存到本地 profile。
  5. Server 重新连接。

授权失败时，优先查看 MCP 设置页的错误信息，再查看 troubleshooting 文档。

在 Agent 中启用 MCP

添加 MCP server 不代表所有 Agent 都能使用它。建议按 Agent 任务域启用必要 server。

在 Agent 中启用 MCP 的步骤：

  1. 打开 Agent 设置。
  2. 进入 MCP / Tools 区域。
  3. 选择需要启用的 server。
  4. 保存 Agent。
  5. 发送一个只读测试任务。

测试任务示例：

请列出你当前可用的 MCP 工具，并说明每个工具适合做什么。不要执行写入操作。

启用时请注意：

  • 工具太多会降低 Agent 选择稳定性。
  • 不要给所有 Agent 启用所有 server。

安全建议

  • 只连接可信 server。
  • 不把敏感环境变量给未知 server。
  • 给 Agent 最小化启用。
  • 授权前阅读权限范围。
  • 对会写入外部系统的工具保持审查。
  • 定期移除不用的 server。

常见 server 类型

GitHub / Git service

用途：issue、PR、repo 信息、代码搜索。

风险：可能创建评论、修改 issue 或访问私有仓库。

Database

用途：查询业务数据或元数据。

风险：敏感数据暴露、写入操作。

Browser

用途：网页自动化和页面读取。

风险：登录态、表单提交、访问第三方网站。

Filesystem

用途：文件读取和写入。

风险：本地敏感文件访问。

Internal API

用途：团队内部系统。

风险：权限边界和审计。

故障排除

工具列表为空

可能原因：server 未连接、server 启动失败、server 没有暴露工具、授权失败。

处理：检查 server 状态，重连，查看日志。

启动失败

可能原因：命令路径错误、环境变量缺失、运行时缺失。

处理：检查配置和 stderr，确认 server 可独立启动。

授权失败

可能原因：OAuth 配置错误、redirect URI 不匹配、用户取消授权。

处理：重新授权，检查 server 文档。

Agent 看不到工具

可能原因：server 添加了但未在 Agent 中启用。

处理：进入 Agent 设置启用该 server。

工具调用报错

可能原因：参数错误、外部服务失败、权限不足。

处理：让 Agent 读取错误信息并重试，或人工检查 server 日志。

下一步