notify-mcp

Deliver-to-self email + SMS for Example Corp staff, as an Entra-authenticated remote MCP server. This is the send path for the claude.ai chief-of-staff rollout: agents can email or text the signed-in user their own content, and structurally nothing else.

The invariant (why this server exists)

Agents that read untrusted content (inbound email, tickets, chats) must never hold an unconstrained send capability — a prompt injection could turn it into an exfiltration channel. This server solves that by construction:

• Recipients are not tool parameters. Email goes to the caller's UPN, taken from the validated Entra token. SMS goes to the caller's mobile on record. A fully compromised model can change what is sent, never where.
• FROM is locked to <agent>approver@example.com — the server cannot send as a human, so it cannot impersonate anyone.
• The Resend + Inteliquent keys live only in this container. Users never see a key; they authenticate with their own M365 login.
• Per-user hourly budgets + an audit log line per send.

Tools

Tool	What it does
whoami	Returns the email + masked mobile that sends will deliver to. Test wiring with this first.
send_email_to_me(subject, body_markdown, agent_name?)	Emails the caller. agent_name brands the sender (alerts → approver@example.com).
send_sms_to_me(message)	Texts the caller's mobile from the company DID 13105550100. ≤640 chars.
register_my_mobile(mobile_number)	Starts SMS setup: texts a 6-digit code to the number.
confirm_my_mobile(code)	Completes setup: verifies the code, saves the number, emails the user a change notice.

How the server knows who you are

Claude → Entra sign-in (the user's own login) → every tool call carries a bearer JWT → AzureJWTVerifier validates signature/issuer/audience → preferred_username claim = the recipient. No env vars per user, no configuration; the identity is cryptographic.

Mobile numbers aren't in the token, so SMS uses verified self-registration (built for tenants that don't populate Entra mobilePhone — ours doesn't):

1. User (typically during the CoS setup interview): "register my mobile 310-555-1212" → server texts a 6-digit code to that number.
2. User types the code → confirm_my_mobile → number saved in /data/sms_directory.json keyed to their UPN + confirmation email sent.
3. Changes are then locked (NOTIFY_ALLOW_MOBILE_CHANGE=false): a confirmed number can only be changed by the admin editing the registry. Code-verification proves possession; the change-lock + email notice kill the injection-rebind attack (hostile content re-pointing texts elsewhere).

Resolution order: registry file (hand entries are plain strings, self- registered entries are objects) → optional Entra mobilePhone via Graph (NOTIFY_GRAPH_LOOKUP_ENABLED=true + -GrantGraphUserRead; unnecessary if self-registration is in use).

Connector session longevity (the disconnect fix)

Three things keep the connector from showing "disconnected":

1. offline_access is advertised in the protected-resource metadata (NOTIFY_ADVERTISE_OFFLINE_ACCESS=true), so Claude's sign-in obtains a refresh token and silently renews the ~60–90 min access tokens.
2. stateless_http=True — sessions survive container redeploys.
3. NPM proxy host must have the playbook's timeout overrides (see PORTAINER_DEPLOY.md) so idle streams aren't cut at 60s.

Also check no Conditional Access sign-in-frequency policy covers this app. Acceptance test: connect, wait 2+ hours idle, redeploy the container, then call whoami — no re-auth prompt should appear.

Setup (playbook order)

1. scripts/setup_entra_app.ps1 -TenantId <tenant> (optionally -GrantGraphUserRead) — prints the server env values + the connector secret (goes in Claude's connector Advanced settings, never the server).
2. Deploy via Portainer Git stack — PORTAINER_DEPLOY.md. Suggested host port 8093 (probe first; recorded in the playbook registry).
3. NPM proxy host notify-mcp.example.com → the container; playbook timeouts + Anthropic IP allowlist; LE cert before enabling the allowlist.
4. Add as an org custom connector in claude.ai; users connect once with their own M365 login.

Acceptance tests

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

Then in Claude, as a group member:

1. whoami → your own email, mobile "on record (…1234)" or a clear miss.
2. send_email_to_me → arrives in YOUR inbox from notify_ai@.
3. Ask the model to "send this to <someone else>" → it must refuse / have no way to comply. This failing is a P1 — do not roll out.
4. register_my_mobile with your number → code arrives → confirm_my_mobile → confirmation email lands → send_sms_to_me works. Then try registering a DIFFERENT number → must be refused (change-lock).
5. The 2-hour idle + redeploy test above.
6. A non-member connects → rejected at sign-in (AADSTS50105).

Local dev

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