notify-mcp

面向 Example Corp 员工的“发送给自己”邮件 + SMS 服务，以 Entra 认证的远程 MCP 服务器形式提供。这是 claude.ai 幕僚长（chief-of-staff）推广计划的发送路径：智能体可以向已登录用户本人发送其自身内容的邮件或短信，除此之外在结构上无法发送给任何其他人。

不变量（此服务器存在的原因）

读取不可信内容（入站邮件、工单、聊天）的智能体绝不能持有不受约束的发送能力——提示注入可能将其变成数据外泄通道。本服务器从构造上解决了这个问题：

• 收件人不是工具参数。 邮件发送到调用者的 UPN（取自经过验证的 Entra 令牌）。短信发送到调用者登记的手机号码。即使模型被完全攻破，也只能改变发送什么，永远无法改变发送到哪。

• 发件人（FROM）被锁定为 <agent>approver@example.com——服务器无法以人类身份发送，因此无法冒充任何人。

• Resend 和 Inteliquent 的密钥只存在于该容器中。用户永远看不到密钥；他们使用自己的 M365 登录进行认证。

• 每个用户每小时配额 + 每次发送的审计日志行。

Related MCP server: graphdo-ts

工具

服务器如何知道你是谁

Claude → Entra 登录（用户自己的登录）→ 每次工具调用都携带 bearer JWT → AzureJWTVerifier 验证签名/签发者/受众 → preferred_username 声明 = 收件人。无需为每个用户设置环境变量，无需配置；身份是加密保证的。

手机号码不在令牌中，因此短信使用经过验证的自我注册（专为不填充 Entra mobilePhone 的租户构建——我们的租户就是如此）：

1. 用户（通常在 CoS 设置访谈期间）：“register my mobile 310-555-1212”→ 服务器向该号码发送 6 位验证码。

2. 用户输入验证码 → confirm_my_mobile → 号码保存到 /data/sms_directory.json，以 UPN 为键 + 发送确认邮件。

3. 此后变更被锁定（NOTIFY_ALLOW_MOBILE_CHANGE=false）：已确认的号码只能由管理员编辑注册表来更改。验证码证明号码所有权；变更锁定 + 邮件通知可消除注入重绑定攻击（恶意内容将短信重定向到其他地方）。

解析顺序：注册表文件（手工条目为纯字符串，自我注册条目为对象）→ 通过 Graph 的可选 Entra mobilePhone（NOTIFY_GRAPH_LOOKUP_ENABLED=true + -GrantGraphUserRead；如果使用自我注册则无需）。

连接器会话持久性（断开连接修复）

三件事可防止连接器显示“已断开”：

1. 在受保护资源元数据中声明 offline_access（NOTIFY_ADVERTISE_OFFLINE_ACCESS=true），因此 Claude 的登录会获取刷新令牌，并静默续签约 60–90 分钟的访问令牌。

2. stateless_http=True——会话在容器重新部署后仍然存活。

3. NPM 代理主机必须具有 playbook 中的超时覆盖（请参阅 PORTAINER_DEPLOY.md），以免空闲流在 60 秒时被切断。

另外，请检查是否有条件访问登录频率策略覆盖此应用。验收测试：连接，空闲等待 2 小时以上，重新部署容器，然后调用 whoami——不应出现重新认证提示。

设置（playbook 顺序）

1. scripts/setup_entra_app.ps1 -TenantId <tenant>（可选 -GrantGraphUserRead）——打印服务器环境变量值 + 连接器密钥（放入 Claude 连接器的高级设置中，绝不放入服务器）。

2. 通过 Portainer Git 堆栈部署——PORTAINER_DEPLOY.md。建议主机端口 8093（先探测；记录在 playbook 注册表中）。

3. NPM 代理主机 notify-mcp.example.com → 容器；playbook 超时 + Anthropic IP 白名单；先启用 LE 证书再启用白名单。

4. 在 claude.ai 中作为组织自定义连接器添加；用户使用自己的 M365 登录连接一次。

验收测试

curl http://<docker-host>:8093/healthz                       # {"status":"ok",...}
curl -s https://notify-mcp.example.com/.well-known/oauth-protected-resource/mcp | jq
#   scopes_supported MUST include the full https://.../mcp/access_as_user scope
#   AND "offline_access"
curl -i https://notify-mcp.example.com/mcp                  # 401 + WWW-Authenticate

然后在 Claude 中，作为组成员：

1. whoami → 你自己的邮箱、手机“已登记（…1234）”或明确的缺失提示。

2. send_email_to_me → 邮件到达你的收件箱，发件人为 notify_ai@。

3. 让模型“把这条发送给<其他人>”→ 它必须拒绝/无法做到。如果失败，则为 P1——不要推广。

4. 用你的号码 register_my_mobile → 收到验证码 → confirm_my_mobile → 确认邮件到达 → send_sms_to_me 正常工作。然后尝试注册一个不同的号码 → 必须被拒绝（变更锁定）。

5. 上述 2 小时空闲 + 重新部署测试。

6. 非成员连接 → 在登录时被拒绝（AADSTS50105）。

本地开发

pip install -r requirements.txt
MCP_AUTH_ENABLED=false python -m notify_mcp   # Inspector only — tools will
                                              # refuse to send without a token
                                              # identity; NEVER expose auth-off