exchange-online-mcp

Exchange Online MCP server — exposes the mailbox, distribution-group and mobile-device operations that Microsoft Graph cannot express, as MCP tools over Streamable HTTP.

What this is for

Microsoft 365 user offboarding needs a handful of actions that only Exchange owns:

Use this server alongside a Microsoft Graph MCP server: user accounts, sign-in blocking, licences, Microsoft 365 groups and security groups stay on the Graph side.

No PowerShell runtime is involved. Every cmdlet runs through the same REST entry point the Exchange Online PowerShell module itself uses:

POST https://outlook.office365.com/adminapi/beta/{tenant}/InvokeCommand
{"CmdletInput": {"CmdletName": "Get-Mailbox", "Parameters": {"Identity": "alice@contoso.com"}}}

Related MCP server: ms-teams-mcp

Tools

Cmdlet output is projected onto a field whitelist and the @odata.type companion keys are stripped, so a typical response is under 1.5 KB instead of the ~40 KB a raw Get-Mailbox returns.

Credentials (HTTP headers)

Exchange Online app-only access accepts certificates only — not client secrets — so the certificate itself is the credential and this server mints the access token per request. Credentials are read from headers only; there is no environment-variable fallback, and nothing is cached between requests.

Missing any required header on /mcp returns 401 with the missing names listed.

Tenant setup

1. Entra admin center → App registrations → New registration (single tenant).

2. API permissions → Add a permission → APIs my organization uses → Office 365 Exchange Online → Application permissions → Exchange.ManageAsApp → Grant admin consent.

3. Create the certificate and upload the public half to the app (Certificates & secrets → Certificates → Upload certificate):

   openssl req -x509 -newkey rsa:2048 -sha256 -days 730 -nodes \
     -keyout exo.key -out exo.crt -subj "/CN=mspbots-exo-mcp"
   openssl pkcs12 -export -out exo.pfx -inkey exo.key -in exo.crt   # upload exo.crt
   base64 -w0 exo.pfx                                               # X-Exo-Certificate

   A PEM bundle works just as well: base64 -w0 <(cat exo.key exo.crt).

4. Assign an Exchange role to the service principal — Entra admin center → Roles and administrators, or Exchange admin center → Roles → Admin roles. Recipient Management covers every tool here; View-Only Organization Management is enough for the two read-only tools. Without a role assignment every cmdlet returns unauthorized.

Certificates expire: rotate them before notAfter and re-upload. One certificate per tenant — this server never shares credentials across tenants.

Endpoints

Environment variables

Unknown environment variables are ignored, never fatal. No credential ever comes from the environment.

Errors

Tools never raise; they return a JSON envelope as their string result:

{"error": {"code": "unauthorized", "message": "...", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. Exchange reports a missing recipient or device as a 400 carrying a cmdlet exception; those are normalised to not_found. An empty list is a successful empty result, never not_found.

Run it

docker compose up --build          # or: docker build --platform linux/amd64 -t exchange-online-mcp:dev .
curl http://localhost:8080/health

uv sync
uv run python -m exo_mcp

Tests

uv run pytest                                   # 50 unit tests, no network
docker build --platform linux/amd64 -t exchange-online-mcp:dev .
uv run python tests/mock_e2e/run_e2e.py         # real container, mocked Entra + Exchange

tests/mock_e2e/ runs the built image against a local stand-in for Entra ID and the admin endpoint: it generates a throwaway certificate, verifies the client assertion the container signs (RS256, x5t, audience), and drives 401 → initialize → tools/list → tools/call for all six tools. No customer tenant required.

Delivery checklist (SOP §14 self-assessment)

Integration contract

• POST /mcp Streamable HTTP; GET /health returns 200 {"status":"ok"}, local-only probe

• Defaults to 0.0.0.0:8080

• Unknown environment variables ignored (SettingsConfigDict(extra="ignore"))

• No session stickiness, no local persistent state

• Credentials read from headers only — no env fallback, no credential fields in config

• Header names follow X-<Vendor>-<Credential> and match this README character for character

• Missing headers → 401 listing them

• Request-scoped isolation via contextvars, reset in finally; no global credential state

• No cross-request caching of tenant data or derived tokens (one token exchange per tool call)

• DNS-rebinding protection disabled

• MCP app's lifespan mounted on the outer Starlette app

• tools/call verified over real HTTP with headers (tests/mock_e2e/)

Errors and network

• Structured error envelope, fixed code vocabulary, no exceptions raised

• Empty results are empty, not not_found; messages carry no credentials

• Outbound timeouts (connect 5s / read 30s; token exchange read 15s)

• Limited retry with backoff on 429/5xx honouring Retry-After; worst case well under 120s

• One shared connection pool, reused within a request

Container and deliverables

• docker build --platform linux/amd64 builds and runs

• Multi-stage build, production stage runs as non-root app

• curl installed in the production stage

• EXPOSE 8080, default MCP_HTTP_PORT/MCP_HTTP_HOST, HEALTHCHECK configured

• uv.lock committed, no private dependency sources

• Credential header table present (above)

Agent-facing design

• 6 tools, modelled on the offboarding flow rather than on endpoints

• Every description ≤ 500 chars (longest 404), first line ≤ 100 chars

• Service-level instructions provided (1027 chars)

• Tools self-describing; required/optional parameters explicit

• All tools prefixed exo_

• exo_list_mobile_devices has limit (default 50, hard cap 200) with has_more

• Returns capped at 20,000 chars, compact separators, ensure_ascii=False

• readOnlyHint / destructiveHint / idempotentHint set on every tool

• Write tools justified by the offboarding SOP; single named resource only, no bulk deletes

• Business flow run by an agent against a real tenant — pending a customer sandbox

Logging and sensitive information

• No credentials, tokens or certificate material logged or echoed in error messages

• No real credentials anywhere in the repo; certificates are generated per test run

• .env / .venv / *.pem / *.pfx / *.key excluded in .gitignore and .dockerignore

Known follow-ups for the first real tenant

• Whether X-AnchorMailbox is required for every cmdlet under app-only auth, and whether the tenant-GUID form (which yields no anchor) is sufficient.

• Whether BypassSecurityGroupManagerCheck is needed for mail-enabled security groups in practice, or should become opt-in.