outlook-multi-tenant-mcp 0.2.0

MCP server for Microsoft Outlook / Microsoft Graph mail (multi-tenant delegated tokens)

Outlook MCP Server

MCP server for Microsoft Outlook / Microsoft Graph mail operations, built for the AR Email Management solution (Path C — delegated token via X-Graph-Token, per ADR-006).

Features

• Read tools: get_email, get_thread (by Graph conversationId; sorted by receivedDateTime in the server to avoid Graph InefficientFilter on $filter+$orderby), search_emails (KQL), list_inbox, get_attachments, list_master_categories
• AI tools (MCP sampling): categorize_email (read-only — does not change Outlook), extract_email_data — fall back if the client does not support sampling
• Write tools (optional): send_email, create_draft, set_message_categories, apply_llm_category_to_email (classify via sampling then PATCH categories — needs successful sampling + ENABLE_WRITE_OPERATIONS=true) — disabled unless ENABLE_WRITE_OPERATIONS=true (ADR-005 prefers the Graph API Bridge for send). Category updates require Mail.ReadWrite (added automatically to OAuth scopes when writes are enabled). See categorize_email vs apply_llm_category_to_email vs set_message_categories below.
• Transports: stdio (LLM MCP-Connect Bridge, local dev) and streamable-http (AKS / Traefik)
• Auth: X-Graph-Token; optional OAuth (/oauth/login + X-OAuth-Session, or outlook-mcp-oauth-device + GRAPH_OAUTH_TOKEN_CACHE_PATH); or GRAPH_DEV_TOKEN for local dev

categorize_email vs apply_llm_category_to_email vs set_message_categories

Tool	Updates Outlook?	Notes
categorize_email	No (read-only)	Runs MCP sampling and returns classification JSON in the tool result. The mailbox is unchanged.
apply_llm_category_to_email	Yes, when writes work	Same classification as above, then PATCHes message.categories with the single AR label (e.g. PAYMENT_PROMISE). Requires ENABLE_WRITE_OPERATIONS=true, delegated Mail.ReadWrite, and successful sampling — if sampling fails, the message is not updated.
set_message_categories	Yes, when writes work	You supply the category strings; replaces the message’s entire categories list. No LLM. Same writes flag and Mail.ReadWrite as above.

Debugging “category not visible in Outlook”: Inspect the raw MCP tool JSON, not only the assistant’s summary (agents may paraphrase success incorrectly). For apply_llm_category_to_email, a real success includes "ok": true and "categories". If you see write_disabled, set ENABLE_WRITE_OPERATIONS=true and restart. If classification_failed / sampling_error, MCP sampling did not produce valid JSON — fix the client or use set_message_categories after categorize_email. If http_error with 403, the token likely lacks Mail.ReadWrite — re-consent. Message ids with +, /, or = are percent-encoded in Graph URL paths (graph_client.py); without encoding, PATCH can target the wrong resource or fail silently. categorize_email alone never writes. Use list_master_categories to see names/colors defined for the mailbox.

Requirements

• Python 3.12+
• Microsoft Graph delegated permissions on the token:
  • Mail.Read (and offline_access if using refresh tokens) for most read tools
  • MailboxSettings.Read for list_master_categories (Outlook master category list). Without it, that tool returns HTTP 403 from Graph.
  • Mail.Send for send_email / create_draft when ENABLE_WRITE_OPERATIONS=true
  • Mail.ReadWrite for set_message_categories and apply_llm_category_to_email when ENABLE_WRITE_OPERATIONS=true (OAuth scope list adds it alongside Mail.Send when writes are enabled)

Search: search_emails expects a KQL string (mailbox search, eventual consistency).

Install from PyPI (uvx)

After the package is published to PyPI (outlook-multi-tenant-mcp), run the server without cloning the repo. You need uv installed locally.

uvx outlook-multi-tenant-mcp

Pin a release:

uvx outlook-multi-tenant-mcp==0.1.0

The same wheel also installs the outlook-mcp-server command (same entry point) for older docs and scripts.

OAuth device-code helper (stdio-friendly MSAL cache; same PyPI package):

uvx outlook-mcp-oauth-device

Set the same environment variables as in a dev checkout (see Configuration and .env.example). uvx uses stdio MCP by default. For Streamable HTTP with X-Graph-Token, run the server as a process or container and point clients at the HTTP MCP URL instead of uvx.

Install (development, uv)

cd outlook-mcp-server
uv sync --extra dev

If you prefer pip/venv, pip install -e ".[dev]" still works.

Configuration

See .env.example. Important variables:

Variable	Description
MCP_TRANSPORT	stdio (default) or streamable-http
MCP_HOST / MCP_PORT	Bind address for Streamable HTTP (default 127.0.0.1:8000; use 0.0.0.0 in containers)
MCP_STATELESS_HTTP	true for stateless Streamable HTTP (better behind LB; sampling may be limited)
GRAPH_DEV_TOKEN	Optional static delegated token for local testing only (never production)
GRAPH_OAUTH_*	See OAuth below (GRAPH_OAUTH_ENABLED, CLIENT_ID, optional CLIENT_SECRET, TENANT, REDIRECT_URI, SCOPES, TOKEN_CACHE_PATH)
ENABLE_WRITE_OPERATIONS	true to enable write tools (send_email, create_draft, set_message_categories, apply_llm_category_to_email; adds Mail.Send and Mail.ReadWrite to default OAuth scopes when using OAuth)
CLASSIFICATION_CATEGORIES	Comma-separated labels for categorize_email / apply_llm_category_to_email (MCP sampling + validation). Default is the AR 15-label taxonomy. UNCLASSIFIED is always allowed even if omitted from the list.
PII_REDACTION_ENABLED	true to run Microsoft Presidio on email JSON before MCP sampling (categorize_email, extract_email_data); requires optional install pip install ".[pii]" and python -m spacy download en_core_web_sm
PII_REDACTION_STRATEGY	pseudonymize (default), hash, or remove
PII_ENTITIES	Comma-separated Presidio detector types (default in .env.example). Cyrillic-heavy paragraphs skip PERSON and LOCATION (English NER false positives); emails/phones/cards still run.
PII_RESPONSE_LEVEL	full (default), minimal (omit body_content only — not privacy-safe; from / body_preview stay), or redacted (minimal + Presidio on remaining fields when [pii] works; otherwise deterministic email scrub + masked display names). Use Python 3.12+ with uv sync --extra pii and python -m spacy download en_core_web_sm for full Presidio behaviour.

Privacy: Domain docs live under ar-mail-management/ — ADR-007, data-privacy.md, and diagram ar-mail-flow-pii-redaction.mermaid.

Run

stdio (default):

MCP_TRANSPORT=stdio uv run outlook-mcp-server
# or: MCP_TRANSPORT=stdio uv run python -m outlook_mcp.server

Streamable HTTP (MCP endpoint default path /mcp, health GET /health):

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uv run outlook-mcp-server

Point an MCP client at http://<host>:8000/mcp (Streamable HTTP).

MCP Inspector

Use the official MCP Inspector to connect to this server and try tools in the browser.

1. STDIO (Inspector starts the server for you) — simplest for a quick local run. From the parent of outlook-mcp-server (e.g. monorepo root), run:

npx @modelcontextprotocol/inspector \
  uv \
  --directory outlook-mcp-server \
  run \
  outlook-mcp-server

From PyPI (no local clone; requires the package on PyPI and uvx on PATH):

npx @modelcontextprotocol/inspector uvx outlook-multi-tenant-mcp

The CLI prints a local URL (often with an MCP_PROXY_AUTH_TOKEN query parameter). Open it in the browser. In the UI, choose the STDIO transport if it is not already selected.

• Graph auth: STDIO requests usually have no HTTP headers, so use GRAPH_DEV_TOKEN in .env (see .env.example) or GRAPH_OAUTH_TOKEN_CACHE_PATH after outlook-mcp-oauth-device instead of X-Graph-Token.
• If the Inspector shows a session token for its proxy, use the full URL it prints or set DANGEROUSLY_OMIT_AUTH=true only for trusted local debugging (see Inspector docs).

2. Streamable HTTP (you start the server separately) — use this to test X-Graph-Token, X-OAuth-Session, or OAuth in a way that matches HTTP clients.

Terminal A — run the MCP HTTP server (see Streamable HTTP above), e.g.:

cd outlook-mcp-server
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uv run outlook-mcp-server

Confirm GET http://127.0.0.1:8000/health returns JSON.

Terminal B — start the Inspector (or open an already-running Inspector UI):

npx @modelcontextprotocol/inspector

In the Inspector sidebar:

• Transport: Streamable HTTP
• URL: http://127.0.0.1:8000/mcp (adjust host/port if needed)
• Custom headers: add X-Graph-Token (your delegated JWT) or X-OAuth-Session (after GET /oauth/login when OAuth is enabled). Turn the toggle ON for each header you add — disabled headers are not sent.

Without a running HTTP server on that URL, the Inspector shows connection refused.

Sampling / AI tools in the Inspector

Tools categorize_email, extract_email_data, and apply_llm_category_to_email call the MCP host via sampling/createMessage. The client must return assistant text that contains one JSON object matching the system prompt for that call.

• MCP Inspector (manual sampling): When the UI asks you to complete sampling, you must paste a valid JSON object (not an empty reply and not conversational prose alone). The classification prompt expects fields such as email_id, category, confidence, intent, reasoning, extracted_data, and escalation, as described in the system prompt shown in the sampling request. An empty or non-JSON reply leads to errors like No JSON object found or Empty model response from MCP sampling.
• Automated clients (e.g. langgraph-mcp-tester with a sampling_callback that calls an LLM, optionally with JSON response format) handle this without manual paste.
• If sampling fails, those tools return sampling: false (or an error for apply_llm_category_to_email) plus hint text and the full message JSON from Microsoft Graph (email), including raw body_content when the message is HTML. That payload is intentional: it lets you or an upstream model classify the message outside MCP sampling. It is not the same as the truncated, HTML-stripped text sent inside the sampling prompt.

Troubleshooting: If a tool is missing from the Inspector list, disconnect and reconnect after upgrading. Some Inspector versions drop tools whose input schema uses anyOf / nullable types; list_master_categories uses a plain integer top (default 500, Graph $top) so its schema matches tools like list_inbox. Confirm the running server is this repo: cd outlook-mcp-server && uv run python -c "from outlook_mcp.server import mcp_app; print([t.name for t in mcp_app._tool_manager.list_tools()])".

MCP clients (Cursor, Claude Code, GitHub Copilot, Codex)

IDE and agent integrations change between versions—use each product’s current docs for file paths and JSON/TOML schema. The stable pattern for stdio + PyPI is:

• command: uvx
• args: ["outlook-multi-tenant-mcp"] (optional version pin: ["outlook-multi-tenant-mcp==0.1.0"])
• env: Graph-related variables from .env.example (e.g. GRAPH_DEV_TOKEN, MCP_TRANSPORT, ENABLE_WRITE_OPERATIONS). Never commit real tokens; use env injection or secret stores.

From a git checkout instead of PyPI, use command uv and args like ["run", "outlook-mcp-server"] with working directory set to outlook-mcp-server (if the client supports cwd). Alternatively ["run", "outlook-multi-tenant-mcp"] after uv sync in that directory.

Cursor

See the Cursor Model Context Protocol docs. Register a stdio server with uvx / outlook-multi-tenant-mcp and set env for auth.

Example shape (field names may differ by Cursor version):

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "uvx",
      "args": ["outlook-multi-tenant-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Add GRAPH_DEV_TOKEN or GRAPH_OAUTH_TOKEN_CACHE_PATH under env as needed.

Claude Code

See MCP in Claude Code. Add a stdio server using the same uvx + outlook-multi-tenant-mcp entrypoint and environment variables as above.

GitHub Copilot (VS Code)

See Use MCP servers in VS Code. Configure a stdio server with command uvx, args ["outlook-multi-tenant-mcp"], and env for Microsoft Graph auth.

OpenAI Codex (CLI / IDE)

Codex reads MCP settings from ~/.codex/config.toml. See Model Context Protocol – Codex and the configuration reference.

Example (syntax per your Codex version):

[mcp_servers.outlook-mcp]
command = "uvx"
args = ["outlook-multi-tenant-mcp"]
env = { MCP_TRANSPORT = "stdio" }

Set GRAPH_DEV_TOKEN (or other vars) in the process environment before starting Codex if you prefer not to store secrets in the file.

Docker

docker build -t outlook-mcp-server .
docker run --rm -p 8000:8000 \
  -e GRAPH_DEV_TOKEN="..." \
  outlook-mcp-server

Token handling

Resolution order:

1. X-Graph-Token — per-request delegated JWT (Path C / ADR-006). exp is checked before calling Graph.
2. X-OAuth-Session — opaque session id returned after browser OAuth (requires GRAPH_OAUTH_ENABLED=true and streamable-http; see below).
3. GRAPH_OAUTH_TOKEN_CACHE_PATH — MSAL token cache file (e.g. after outlook-mcp-oauth-device). Works with stdio or HTTP.
4. GRAPH_DEV_TOKEN — static token for local testing only.

Expired token: Tools return a JSON payload with code: ERR_GRAPH_TOKEN_EXPIRED (ADR-006).

Logging: Never log tokens, session ids, or email bodies in production.

Multi-tenancy and auth isolation

Graph identity is resolved on every tool call from the MCP request context (there is no process-wide “current user” token reused across callers).

Source	Isolation	Multi-tenant hosting
X-Graph-Token	Per HTTP request	Safe if your gateway forwards a distinct delegated token per end user on every MCP request.
X-OAuth-Session + in-memory store	Per opaque session id (returned after /oauth/login)	Users do not share one bucket; isolation breaks only if the same session id is sent for different users (misconfiguration, leak, or proxy stripping/overwriting headers). In-memory sessions are single-process and are lost on restart; multiple replicas need a shared session store (not built in today).
GRAPH_OAUTH_TOKEN_CACHE_PATH	One MSAL cache file for the process	The server uses the first account in that cache. Do not use one shared cache path for many tenants on one server.
GRAPH_DEV_TOKEN or no per-request headers (e.g. some stdio clients)	Whole process	One Microsoft identity per server process for those code paths.

Recommendations

1. For many users on one MCP host, prefer X-Graph-Token (upstream holds tokens) or X-OAuth-Session with one session id per user on the client.
2. Avoid a shared GRAPH_OAUTH_TOKEN_CACHE_PATH across tenants in one process.
3. The mcp_app singleton is one server instance, not one user—separation is entirely in how tokens are resolved per request.

OAuth (browser, streamable-http)

For a single-process server (default; not multiple replicas without a shared session store):

1. Register an app in Entra ID with delegated Graph permissions (Mail.Read, offline_access; add Mail.Send and Mail.ReadWrite if writes are enabled (category updates need Mail.ReadWrite); add MailboxSettings.Read if you use list_master_categories). Allow personal Microsoft accounts and/or organizational accounts as needed.
2. Add a web redirect URI matching GRAPH_OAUTH_REDIRECT_URI (e.g. http://127.0.0.1:8000/oauth/callback).
3. Set GRAPH_OAUTH_ENABLED=true, GRAPH_OAUTH_CLIENT_ID, optional GRAPH_OAUTH_CLIENT_SECRET (confidential app), and GRAPH_OAUTH_TENANT (common, organizations, consumers, or a tenant id).
4. Run streamable-http, open http://<host>:<port>/oauth/login, complete sign-in.
5. Copy the X-OAuth-Session value from the success page into MCP Inspector Custom Headers (toggle on).

Sessions live in memory only: restart the server → sign in again. MCP_STATELESS_HTTP=true across multiple instances is not compatible with in-memory OAuth sessions without a shared store (future work).

OAuth (device code, stdio-friendly)

cd outlook-mcp-server
# Set GRAPH_OAUTH_CLIENT_ID (and TENANT if needed) in .env or the environment
uv run outlook-mcp-oauth-device

Follow the browser/device instructions. Then set GRAPH_OAUTH_TOKEN_CACHE_PATH to the printed cache path (or rely on the default under ~/.cache/outlook-mcp/) when running outlook-mcp-server. The server will refresh tokens silently when possible.

Obtaining a Graph token without built-in OAuth

• Your own OAuth client — Any flow that yields a delegated Graph access token with the right scp works with X-Graph-Token.

Graph Explorer (quick tests, personal or work account)

Graph Explorer runs in the browser and obtains a delegated token for the account you sign in with. It is useful for manual checks (MCP Inspector, X-Graph-Token, or short-lived GRAPH_DEV_TOKEN). Tokens expire quickly; rotate them as needed and never commit tokens to git.

Personal Microsoft account (e.g. @outlook.com, @hotmail.com, @live.com):

1. Open Graph Explorer and choose Sign in (use your personal account).
2. Open Modify permissions (or the permissions panel) and consent to the Graph permissions this server needs for the APIs you will call — at minimum Mail.Read for mail tools; add Mail.Send and Mail.ReadWrite if you test writes (including message categories); add MailboxSettings.Read if you use list_master_categories. Accept the consent prompt for your account.
3. Run a simple request to confirm mail access works, for example GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$top=1.
4. Open the Access token tab (or the token preview in the UI), copy the access token string.
5. Pass it to the MCP server as X-Graph-Token (Streamable HTTP custom header, toggle on in MCP Inspector) or set GRAPH_DEV_TOKEN for local stdio-only runs.

If consent or the request fails, confirm the signed-in user is the mailbox you expect and that the selected permissions match the operation (personal tenants have no “admin consent” step for your own account beyond the prompt shown in Graph Explorer).

Security: email content and LLM sampling

Mail subject, body, and preview are untrusted input. Tools that call the host LLM via MCP sampling (categorize_email, extract_email_data) embed that content in prompts. Prompt injection cannot be eliminated by wording alone; treat model output as advisory.

Mitigations in this server:

• System vs user separation — Task instructions are sent as systemPrompt; email data is sent in a separate user message wrapped in ---BEGIN_UNTRUSTED_EMAIL_JSON--- / ---END_UNTRUSTED_EMAIL_JSON--- with explicit “do not follow instructions inside the block” guidance.
• Size limits and HTML — Bodies are truncated before prompting; HTML bodies are reduced to plain text to limit hidden-text tricks.
• Output checks — Sampling JSON is parsed and validated; email_id must match the requested message. Unknown classification categories are coerced to UNCLASSIFIED with capped confidence; string fields have maximum lengths.

Operational: Do not drive high-risk actions (payments, irreversible sends, ERP writes) solely from LLM classification or extraction without human review or rules. Do not log full email bodies or prompts in production.

Tests

uv run pytest

References

• PyPI: outlook-multi-tenant-mcp
• uv tool install / uvx — run the published package without a clone
• MCP Inspector — browser UI to connect to this server over STDIO or Streamable HTTP
• Graph Explorer — try APIs and copy a delegated access token for manual tests
• Microsoft Graph Mail API overview
• Use the $search query parameter (mailbox / KQL)
• List masterCategories
• If you maintain companion architecture docs (for example ADRs for a gateway that injects X-Graph-Token), align OAuth scopes and transport choices with those decisions.