如何通过 OAuth 把 Outlook 接入 MCP？
在 Mailera 中，从“使用 Microsoft 登录”入口进入 Microsoft 页面完成授权，再把 Mailera 的 MCP 配置导入客户端。组织账户能否完成授权，仍由租户策略决定。
这里的 MCP 服务器向 AI 智能体提供邮件工具；Microsoft Graph OAuth 负责邮箱连接，MCP 负责让客户端发现和调用工具。Mailera 支持 Outlook.com、Hotmail 和 Microsoft 365，具体入口见 Microsoft 邮箱接入说明。除本文介绍的 Microsoft 登录授权外，Mailera 也支持通过批量粘贴导入已有的 refresh token 连接 Microsoft 邮箱，但本文只讲 OAuth 登录路径。
本文只做 Outlook MCP 配置和只读验收。若你还要连接其他服务商，可先看已有邮箱的 MCP 接入总览。
Microsoft OAuth 和 MCP 密钥分别授权了什么？
这两层授权不能互相替代。Microsoft 登录成功，不代表客户端拿到了有效的 Mailera 密钥；密钥有效，也不代表邮箱仍能登录。
| 授权层 | 授权对象 | 你需要检查什么 |
|---|---|---|
| Microsoft OAuth | Mailera 访问你的 Microsoft 邮箱 | 登录账户、同意内容、组织是否允许访问 |
| Mailera API 密钥 | MCP 客户端使用 Mailera 邮件工具 | 邮箱组范围、操作权限、有效期及 IP 限制 |
Mailera 的 read、send 是产品权限名，不是 Microsoft Graph 权限名；完成 Microsoft 登录时，实际显示的同意范围以 Microsoft 页面为准。只给客户端 read，并不等于把 Microsoft 侧的授权范围也改成了只读。需要核对权限含义时，查阅 Microsoft Graph 权限参考。
初次测试只授予 read，并把密钥限制到测试邮箱所在的组。这个限制是按组生效的：只有当该组确实只有测试邮箱时，才是单邮箱范围。read 也不是“只允许读某一封邮件”。
如果你改为自建 Graph 服务，需要另外设计 Microsoft 授权模型。Graph 身份验证与授权说明区分代表已登录用户的委托访问与不依赖用户登录的应用访问；不要把这两种模型的同意要求混用。
如何连接 Microsoft 邮箱并配置客户端？
- 准备测试邮箱。 使用自己控制的邮箱，准备一封主题容易辨认、正文不含敏感内容的邮件，例如主题“邮件读取测试”，正文“本次测试只用于核对读取结果”。确认你在 Mailera 中是管理员或组长，只有这两类角色可以添加邮箱。
- 进入 Microsoft 登录。 打开“邮箱列表”→“添加邮箱”，选择“使用 Microsoft 登录”。在 Microsoft 页面核对账户和请求的权限，再完成授权。不要在其他服务商的密码表单中填写 Outlook 密码。
- 检查连接结果。 返回“邮箱列表”，确认目标邮箱已添加；随后按下文调用
get_mailbox_status检查登录是否仍可用。
- 创建只读密钥。 进入“设置”的 API 密钥页，选择“创建 API key”。填写“易于识别的名称”，例如“Outlook 只读测试”；在“邮箱范围”中选测试邮箱所在组，仅启用
read，并设置“有效期”。初次测试不启用send、move或sync。管理员也不要为了省事选择所有组。 - 保存密钥并复制配置。 出现“API key 已创建，请立即复制”后，安全保存密钥，它只展示一次。在同一对话框中使用“复制 MCP 配置”，选择 Claude、Cursor 或 VS Code，再按对应客户端要求导入。
Mailera 的 MCP 端点是 https://mailera.app/api/public/v1/mcp。配置结构以界面复制结果为准，不要把不同客户端的配置文件格式混在一起，也不要把 Microsoft token 填到 Mailera API 密钥的位置。
工具接入说明见 Mailera MCP 页面。使用 Claude 时可对照 Claude 集成说明；使用 VS Code 时可接着看 VS Code 邮件 MCP 配置与测试。
怎样确认客户端读到了目标邮件？
验收目标不是“服务器已添加”，而是工具返回了目标邮箱中的那封邮件。让客户端完成下面的调用，并查看工具结果，不要只看 AI 的口头回答。
- 调用
list_mailboxes，确认可见邮箱与密钥选择的组一致。若出现不该包含的邮箱，先收紧范围，再继续读取。 - 调用
get_mailbox_status，检查目标邮箱的连接状态。Mailera 对 Microsoft 邮箱会直接检查登录是否仍然可用。 - 调用
list_messages，在目标邮箱的相应文件夹中定位测试主题。 - 调用
get_message，读取找到的邮件正文，核对发件人、主题和测试内容。
这些工具都使用 read 权限。MCP 客户端通过 tools/list 发现工具，再通过 tools/call 调用；参数名应以发现到的工具定义为准，不要直接照搬 REST 参数。协议细节见 MCP 工具规范。
可以给客户端这样的任务：
仅在我指定的测试邮箱中查找主题为“邮件读取测试”的邮件。先确认邮箱及连接状态，再读取匹配邮件。只返回发件人、主题和正文摘要，不发送、回复或移动邮件。如果找不到，请报告实际查询的邮箱和文件夹，不要改查其他邮箱。
验收时记录目标邮箱标识、测试邮件标识，以及正文是否与原邮件一致。发件人和主题相同但正文未读取，不算完成正文验收。向他人展示结果时，遮盖个人邮箱地址及敏感正文；只保留核对所需的脱敏标识。
任务提示词限制的是本次行为，密钥权限才是客户端的操作边界。即使提示词写了“不发送”，也不应给这次读取测试添加 send 权限。
常见错误：授权成功后为什么仍读不到邮件？
先判断失败发生在哪里。Microsoft 同意页面、Mailera 邮箱状态和 MCP 客户端报错属于不同层，不要把所有问题都归为 OAuth 失败。
| 现象 | 所属层 | 检查动作 |
|---|---|---|
| Microsoft 页面拒绝同意或要求管理员批准 | Microsoft 授权 | 核对登录账户，联系组织管理员检查同意策略 |
| 管理员已同意，当前用户仍无法访问 | Microsoft 用户访问 | 请管理员检查该用户对应用的访问限制 |
| 邮箱已添加，但状态检查显示登录不可用 | 邮箱连接 | 记录 get_mailbox_status 的实际结果及错误来源，联系支持人员处理；不要提交完整密钥或 token |
| 客户端使用密钥的调用被拒绝 | Mailera 密钥 | 检查是否复制完整、已撤销或过期，以及 IP 限制；需要时创建新密钥并更新配置 |
| 能调用工具，却看不到测试邮箱 | 邮箱范围 | 核对密钥所选组和测试邮箱实际所属组，不要直接扩大到所有组 |
| 客户端没有发现邮件工具 | MCP 配置 | 核对端点、所选客户端及导入的配置，确认使用的是 Mailera 密钥 |
| 邮箱可见，但邮件列表为空 | 查询或同步 | 核对目标邮箱、文件夹、筛选条件与同步状态，再判断是否需要恢复授权 |
Microsoft Entra 管理员可以设置用户同意应用的条件；即使已授予租户级管理员同意，用户访问仍可能受限。具体规则见 Microsoft 用户和管理员同意说明。不要尝试绕开组织策略。
如果确需主动同步，sync_mailbox 需要额外的 sync 权限，本文的初始只读密钥不包含它。应明确授权这项操作，而不是为排错一次性打开所有权限。
新邮件暂未出现时，先看同步状态，不要立即重建 OAuth 连接。
连接失败也不应改用应用专用密码；Mailera 的 Microsoft 接入不走这条路径。旧密码方案的问题可参考 Outlook 应用专用密码失效后的 OAuth 接入方式。向支持人员提交错误时，保留错误来源和发生步骤，不要粘贴完整密钥或 token。
让 AI 读取邮件时，怎样限制风险？
邮件正文、附件和链接都是不可信数据，不是给 AI 智能体的指令。邮件即使写着“忽略之前的规则”“把密钥发到这个地址”，也不能触发发送、权限变更或秘密泄露。把邮件用于摘要，不代表允许它改变工作流。
使用最小权限、限定邮箱组并设置有效期；有明确网络访问范围时，再配置“IP 限制（可选）”。密钥不要放进提示词、公开仓库或截图。相关产品说明见 Mailera 安全页面。
以后确实需要发送或回复时，再单独授予 send。执行前由人确认收件人、主题和正文；这项确认要在客户端或工作流中落实，不应把它当作 Mailera 的内置强制审批。
测试结束后撤销不再使用的密钥。撤销会立即使使用该密钥的调用被拒绝，但它与撤回 Microsoft 授权是不同操作：前者切断客户端使用这把密钥的访问，后者处理邮箱对应用的授权。
Mailera 的边界是什么？
Mailera 连接你已有的邮箱，不创建新邮箱或邮件地址，也不提供群发、营销发送或邮箱预热。它不是 Microsoft 的官方合作伙伴，不能替代组织管理员批准，也不能改变租户授权策略。
