Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: connect a Microsoft 365 (Entra ID) remote MCP server

Diego Zacariasd245b90b3afd
diff --git a/docs/README.md b/docs/README.md
index 6e346a168..7828c725b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -55,7 +55,7 @@ say so. [Design records](#design-records) are point-in-time and not maintained.
| [Connect Microsoft Teams](how-to/connect-teams.md) | Teams CLI bot registration, endpoint, conversation verify |
| [Use the Desktop App](how-to/use-the-desktop-app.md) | Daily use: chat, attachments, approvals, EvenDrive, shortcuts, deep links |
| [Configure guardrails](how-to/configure-guardrails.md) | Tool-call rules, installed guardrail hooks, built-ins |
-| [Connect an OAuth connector](how-to/connect-oauth-connector.md) | Remote and OAuth MCP servers, user authorization, connector credentials |
+| [Connect an OAuth connector](how-to/connect-oauth-connector.md) | Remote/OAuth MCP servers, Microsoft 365 (Entra ID), user auth, secrets |
| [Configure approvals](how-to/configure-approvals.md) | Human-in-the-loop tool gates |
| [Add an MCP server](how-to/add-mcp-server.md) | Dev-mode JSON, CRD, or Control UI path |
| [Desktop setup & updates](how-to/desktop-setup-and-updates.md) | Environments, invitation setup, updates |
diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.md
index ee7b53ba1..5c62fc4fb 100644
--- a/docs/crds/mcpserver.md
+++ b/docs/crds/mcpserver.md
@@ -81,6 +81,7 @@ after creation:
| `oauth.authorizationEndpoint`, `tokenEndpoint`, `resource` | remote, generic | Pinned endpoints; `resource` is the RFC 8707 resource indicator. |
| `oauth.registrationEndpoint`, `issuer`, `issForCallback` | remote | Dynamic client registration URL, issuer, and the RFC 9207 `iss` validated on callback. |
| `oauth.bearerInBody`, `supportsRefresh` | remote (`supportsRefresh` also generic) | Pinned at install. `bearerInBody` must be `false`. |
+| `oauth.asProfile` | remote | Optional. Closed authorization-server profile, set at install when the pinned issuer is recognised. Only value: `entra-v2` (Microsoft Entra ID v2, tenant authority): the RFC 8707 `resource` is not sent, `offline_access` is always requested, and the scopes are sent on the code exchange and on refresh. Requires a Microsoft Entra tenant issuer (see the AS-PROFILE-ISSUER rule below). With `entra-v2`, control-api also checks `oauth.scopes` against the host of `spec.remote.baseUrl` at install and at runtime; see [Scopes and audience](../how-to/connect-oauth-connector.md#scopes-and-audience). Immutable. |
| `oauth.tokenRequestFormat`, `tokenAuthMethod`, `scopeSeparator`, `sendScope`, `usePkce`, `includeResponseType`, `refreshEndpoint`, `extraAuthorizeParams` | generic | Wire options for non-standard authorization servers. |
**Redirect URI to register** with the provider:
@@ -247,6 +248,15 @@ API translates to this explicit `egressClass: public-web` CRD shape.
- Each egress binding must have exactly one of `dns` or `cidr` (not both, not neither).
- A `cidr` must be a canonical public IPv4 range; ranges overlapping private, metadata, link-local, documentation, multicast, or reserved IPv4 ranges (including `0.0.0.0/0` and RFC1918 ranges such as `10.0.0.0/8`) are rejected.
- An McpServer with `spec.remote` must declare at least one `egressBinding`.
+- `spec.oauth.asProfile` is remote-only: built-in (no `source`) and `generic` servers must not set it.
+- On a `remote` server, `spec.oauth.asProfile` is immutable like the other pinned fields: it cannot be added, removed, or changed after creation. Delete and recreate the server to change it.
+- **AS-PROFILE-ISSUER:** when `spec.oauth.asProfile` is set, `spec.oauth.issuer` must be a Microsoft Entra ID tenant authority, matching `^https://login[.]microsoftonline[.]com/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/v2[.]0$` (lower-case tenant GUID, no trailing slash). Otherwise the write is rejected with `spec.oauth.asProfile entra-v2 requires spec.oauth.issuer to be a Microsoft Entra ID tenant authority`. A profile stops sending the RFC 8707 `resource`, so it must stay on the issuer it was recognised from. control-api applies the same check at runtime and refuses an object written before the rule was in the cluster (`409 remote_oauth_spec_incoherent`, reason `as_profile_issuer_mismatch`).
+
+> **Apply the CRD before control-api.** An apiserver whose McpServer CRD does not
+> declare `asProfile` drops the field on write and still answers 200. The server
+> is then installed without the profile: control-api sends the RFC 8707
+> `resource`, which Entra rejects. See
+> [Deploy order for additive schema fields](../../charts/clerum-crds/README.md#deploy-order-for-additive-schema-fields).
## Example
diff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.md
index 0a405ea5c..4c30c68a9 100644
--- a/docs/how-to/connect-oauth-connector.md
+++ b/docs/how-to/connect-oauth-connector.md
@@ -83,9 +83,13 @@ Context they belong to. Otherwise the request fails with
the **Context** to attach the server to. Click **Detect**.
control-api runs RFC 9728/8414 discovery and probes the MCP endpoint. If the
endpoint is unreachable, the wizard stays on this step and may suggest the
- correct URL.
-3. **Configure**: review the detected issuer, endpoints, scopes, and
- **Registration mode**. The mode is picked in this order:
+ correct URL. If the server signs in through Microsoft Entra ID, the wizard
+ asks for your tenant ID first; see
+ [Microsoft 365 / Entra ID](#microsoft-365--entra-id).
+3. **Configure**: review the detected issuer, endpoints, and
+ **Registration mode**. **Scopes** starts with the scopes the server
+ advertises; edit the space-separated list if needed, or clear it to go back
+ to the advertised ones. The mode is picked in this order:
- **Client ID Metadata Document (public client)**: no credentials. Picked
automatically when the server supports RFC 9207 `iss`, advertises CIMD,
and accepts public clients. The client ID is a URL on your callback
@@ -122,6 +126,228 @@ with an exact-host egress binding to port 443 of the remote host. API
equivalents: `POST /api/v1/admin/mcp-servers/remote/discover` (dry run) and
`POST /api/v1/admin/mcp-servers/remote`.
+## Microsoft 365 / Entra ID
+
+Microsoft 365 MCP servers sign users in with Microsoft Entra ID. You add them
+with the same **Add remote server** wizard, but Entra needs a tenant ID, a
+pre-registered app, and scopes that name the server's own API. This section
+covers [Work IQ](#work-iq-recommended), which is the recommended server, and
+the [Agent 365](#agent-365-legacy-not-verified) per-app servers, which
+Microsoft marks as legacy.
+
+> **Pending end-to-end verification.** This flow is covered by automated
+> tests built from metadata captured from Microsoft's servers, but it has not
+> yet been run end to end against a real tenant. Which scope form Work IQ
+> accepts is not settled yet, and Agent 365 is **not verified**.
+
+### What changes with Entra ID
+
+- **Tenant ID.** These servers advertise Entra's multi-tenant authority
+ (`https://login.microsoftonline.com/organizations/v2.0`), whose metadata
+ cannot be matched to a single issuer. After **Detect**, the wizard asks for
+ the **Microsoft Entra tenant ID**: the **Directory (tenant) ID** on the
+ Microsoft Entra admin center overview. Enter it as a GUID. A domain name
+ such as `contoso.com` is refused, because Entra reports the issuer with the
+ GUID and a domain could never match it. The wizard lowercases the GUID and
+ detects again against `https://login.microsoftonline.com/<tenant-id>/v2.0`.
+ A tenant Entra does not know shows "Microsoft Entra ID did not recognize
+ this tenant ID". The override is accepted only for Entra: control-api
+ rejects a tenant authority for a server that does not advertise Entra's
+ multi-tenant authority, and any other authorization server address.
+- **One install per tenant.** The tenant is pinned at install, and users sign
+ in against it. To serve several tenants, install the server once per tenant,
+ each with its own server name and app registration.
+- **Authorization server profile.** The Configure step shows
+ **Authorization server: Microsoft Entra ID**, and the McpServer is
+ installed with `spec.oauth.asProfile: entra-v2`. With this profile,
+ control-api:
+ - uses PKCE (S256) and refresh tokens. Entra supports both but does not
+ advertise them in its metadata;
+ - always adds `offline_access`, because Entra only issues a refresh token
+ when it is requested. You do not need to type it;
+ - does not send the RFC 8707 `resource` parameter, because Entra picks the
+ token's audience from the scopes and rejects a `resource` that disagrees.
+ The wizard shows the resource as "(not sent to Microsoft Entra ID)";
+ - sends the installed scopes on the code exchange and on every refresh, so
+ the installed scopes, not the authorize URL that passes through the
+ browser, decide which API the token is for.
+- **Pre-registered client.** Entra offers neither dynamic registration nor a
+ client ID metadata document, so the mode is **Pre-registered client
+ required**. Use a client secret. Certificate credentials are not supported.
+- **Grant scope.** Use **Per user** for Microsoft 365, so each user's agents
+ act with that user's own mailbox, files, and permissions.
+
+### App registration: one per server
+
+In the Microsoft Entra admin center, under **App registrations**, create a
+separate app registration for each MCP server (Work IQ, Agent 365 Mail,
+Agent 365 Calendar, and so on):
+
+1. **Platform: Web.** Add the redirect URI the wizard shows, exactly:
+ `<CONTROL_API_OAUTH_CALLBACK_BASE_URL>/api/v1/oauth-callback/remote/<serverName>`.
+ Entra accepts an `http` redirect URI only with `localhost`, so on a local
+ cluster use `http://localhost:<port>` as the callback base.
+2. **Client secret.** Create one under **Certificates & secrets**, and paste
+ it with the **Application (client) ID** into the wizard.
+3. **API permissions.** Remove the Microsoft Graph `User.Read` permission that
+ Entra adds by default. Add only the delegated permission of this server,
+ then **Grant admin consent**.
+4. **Block user consent for the app.** Entra lets users consent at sign-in to
+ permissions the app registration does not list, so the permission list is
+ not a ceiling on its own. It becomes one when users cannot consent: set
+ the tenant's user consent setting to **Do not allow user consent**
+ (Enterprise applications > Consent and permissions > User consent
+ settings), or use an app consent policy that excludes this app. Then the only permission a token can carry is the one
+ an administrator consented to.
+
+control-api refuses to install a second server with the same client ID
+(`409 oauth_client_id_in_use`), so reusing one app registration across servers
+is not possible.
+
+### Scopes and audience
+
+Because the `resource` parameter is not sent, the scopes alone decide which
+API a token is issued for, and mcp-host sends that token to the MCP server.
+control-api therefore checks every scope against the host of the server URL
+before it installs anything. The scopes come from the server's metadata or
+from you, and both are checked the same way.
+
+| Scope | Result |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `openid`, `profile`, `email`, `offline_access` | Allowed, but not enough on their own (see below). |
+| `https://<server-host>/...` or `api://<server-host>/...`, where `<server-host>` is exactly the host of the server URL | Accepted. |
+| GUID form (`<guid>/<permission>` or `api://<guid>/<permission>`, lower-case GUID) of a Microsoft MCP API on its own host: Work IQ `fdcc1f02-fc51-4226-8753-f668596af7f7` on `workiq.svc.cloud.microsoft`, Agent 365 Tools `05879165-0320-489e-b644-f72b33f3edf0` on `agent365.svc.cloud.microsoft` | Accepted. |
+| GUID form of a blocked Microsoft API (list below) | Always rejected (`scope_audience_mismatch`), even if you confirm it. |
+| Any other GUID form, including a known one on a different host | Accepted only after you confirm it (`scope_audience_unverified`). |
+| Anything else: a bare permission such as `Mail.Read` (Entra reads it as Microsoft Graph), a URL on another host, or a URL with a user name or port | Rejected (`scope_audience_mismatch`). |
+
+**Blocked APIs.** Microsoft Graph, SharePoint Online, Exchange Online, Azure
+Service Management, Azure AD Graph, Azure Key Vault, Azure Storage, Office 365
+Management APIs, Microsoft Intune, Microsoft Defender for Endpoint
+(WindowsDefenderATP), and Skype for Business Online. These are high-impact
+Microsoft APIs that never host an MCP server, so a token for them must never
+reach one.
+
+**The server's own scope is required.** At least one scope must name the
+server's API (a URL on its host, or a GUID form that is accepted or
+confirmed). With sign-in scopes only, Entra issues a Microsoft Graph token,
+so the install is rejected with `scope_audience_missing`. If the advertised
+scopes break a rule, the Configure step shows a warning so you can fix the
+list before installing.
+
+**Confirming an unverified scope.** When a GUID scope names an API the
+platform cannot tie to the server, the Confirm step lists those exact scopes
+with the check box **I confirm these scopes belong to this server's own API**.
+The confirmation covers exactly the strings listed: if you go back and change
+the scopes, the wizard asks again. Through the API, send each one, as the
+exact string, in `confirmedUnverifiedScopes`. control-api logs each
+confirmation as the audit event `remote_install_unverified_scopes_confirmed`,
+with the confirming admin and the scopes.
+
+**Editing the McpServer later.** Writing the McpServer directly
+(`PUT /api/v1/admin/mcp-servers/<name>` or `kubectl`) counts as confirming its
+unverified GUID scopes: whoever can write the resource can already change its
+server URL. It does not bypass the other rules. On every authorization,
+callback, token use, and refresh, control-api checks the scopes again against
+the current `spec.remote.baseUrl`. A blocked API, a URL on another host, a
+bare permission, or a missing server scope is refused with
+`409 remote_oauth_spec_incoherent` (reason `scope_audience_mismatch`), and
+existing grants stop being served until the resource is fixed.
+
+> **Limit with GUID scopes.** A GUID scope is not tied to a host, so if only
+> `spec.remote.baseUrl` changes, the platform cannot tell that the token now
+> goes to a different server. Prefer the URL form (`api://<server-host>/...`)
+> when the server accepts it.
+
+Ask for scopes of one API only. Entra issues each token for a single
+resource, so mixing scopes of different APIs, or `.default` with specific
+scopes, fails when the user connects.
+
+**Not supported:**
+
+- MCP servers whose scope lives on a different host than the server, such as
+ Power BI (`api.fabric.microsoft.com/v1/mcp/powerbi`, with scopes on
+ `analysis.windows.net`). The URL form is rejected, and the GUID form with
+ confirmation has not been verified.
+- National clouds (`login.microsoftonline.us`, `login.partner.microsoftonline.cn`),
+ personal Microsoft accounts (`consumers`), and the v1 authority
+ (`sts.windows.net`).
+- A tenant given as a domain name, and certificate client credentials.
+
+### Work IQ (recommended)
+
+Server URL: `https://workiq.svc.cloud.microsoft/mcp`.
+
+**Tenant prerequisites:**
+
+- The Work IQ service principal. Create it once if your tenant does not have
+ it: `az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7`.
+- Microsoft's billing requirements in
+ [Enable Work IQ](https://learn.microsoft.com/microsoft-365/copilot/extensibility/work-iq/enable-work-iq):
+ a pay-as-you-go billing plan backed by an Azure subscription, with the users
+ who will connect assigned to that plan. Check that page for the current
+ terms.
+
+**App registration:** only the delegated permission `WorkIQAgent.Ask` of the
+Work IQ API, with admin consent.
+
+**Scopes.** Both forms are accepted without confirmation:
+
+| Scope | Notes |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask` | The form Microsoft's quickstarts use. **Try this one first**: it is tied to the host, so a later change of `spec.remote.baseUrl` is detected. |
+| `fdcc1f02-fc51-4226-8753-f668596af7f7/WorkIQAgent.Ask` | The form the server advertises, and the one the wizard prefills. |
+
+Replace the prefilled scope with the `api://` form, then install.
+`offline_access` is added for you.
+
+> **Pending end-to-end verification.** It is not yet confirmed which of the
+> two forms Work IQ accepts. If the user connects but tool calls fail with
+> `401`, delete the server and install it again with the GUID form.
+
+### Agent 365 (legacy, not verified)
+
+Microsoft states that the Agent 365 tooling servers are "only intended for
+backward compatibility purposes and shouldn't be used in production
+environments or new projects"
+([Agent 365 tooling servers](https://learn.microsoft.com/microsoft-agent-365/tooling-servers-overview)).
+Use [Work IQ](#work-iq-recommended) for new work.
+
+> **Not verified.** This setup has not been run end to end. It is also not
+> confirmed that Agent 365 accepts tokens issued to a regular app
+> registration.
+
+Server URL, for example Mail:
+`https://agent365.svc.cloud.microsoft/agents/tenants/<tenant-id>/servers/mcp_MailTools`.
+
+**Tenant prerequisites:**
+
+- Agent 365 enabled in the tenant, and the server listed in the Microsoft 365
+ admin center under **Agents > Tools**.
+- The Agent 365 Tools service principal, created once per tenant by a Global
+ Administrator with the `New-Agent365ToolsServicePrincipalProdPublic.ps1`
+ script from the `microsoft/Agent365-devTools` repository.
+
+**App registration:** one per Agent 365 server (Mail, Calendar, Teams, and so
+on), each with only that server's delegated permission from the Agent 365
+Tools app (`05879165-0320-489e-b644-f72b33f3edf0`), for example
+`McpServers.Mail.All` for Mail. See
+[Agent 365 tooling for developers](https://learn.microsoft.com/microsoft-agent-365/developer/tooling).
+
+**Scopes.** control-api accepts these three forms without confirmation. Try
+them in this order and keep the first one whose tool calls succeed:
+
+1. The advertised scope, which the wizard prefills:
+ `https://agent365.svc.cloud.microsoft/agents/tenants/<tenant-id>/servers/mcp_MailTools/.default`.
+ Every Agent 365 server and tenant shares this host, so the host check does
+ not tell Mail from Calendar.
+2. The form in Microsoft's manifest:
+ `api://05879165-0320-489e-b644-f72b33f3edf0/McpServers.Mail.All`.
+3. The bare GUID form: `05879165-0320-489e-b644-f72b33f3edf0/McpServers.Mail.All`.
+
+Forms 2 and 3 are not interchangeable: depending on how a token is requested,
+its audience can be the application ID URI or the application ID.
+
## Operator: built-in or generic provider (YAML)
Create an OAuth app at the provider, register the redirect URI, and store the
@@ -263,6 +489,13 @@ out too, but the screen only tracks the current one.
| Users must authorize again after a reinstall | Grants are bound to the old McpServer UID | Expected |
| Connector shows **Missing Secret** | `SecretResolved=False` | Use **Set credentials** on the **Credentials** tab |
| Rotation restarted other connectors | They share the same `envSecret` | Expected. Check `affectedConnectors`. |
+| **Detect** asks for a Microsoft Entra tenant ID | The server signs in through Entra's multi-tenant authority (`tenant_required`) | Enter the Directory (tenant) ID as a GUID |
+| "Microsoft Entra ID did not recognize this tenant ID" | The GUID is not a tenant Entra knows | Copy the Directory (tenant) ID from the Microsoft Entra admin center overview |
+| Install returns `scope_audience_mismatch` | A scope names another API: a blocked Microsoft API, a URL on another host, or a bare permission | Use the server's own scope. See [Scopes and audience](#scopes-and-audience) |
+| Install returns `scope_audience_missing` | Only sign-in scopes (`openid`, `profile`, `email`, `offline_access`) | Add the server's own scope |
+| Install asks to confirm scopes (`scope_audience_unverified`) | A GUID scope names an API the platform cannot tie to the server | Confirm only if that API belongs to the server; otherwise change the scope |
+| `409 oauth_client_id_in_use` | The app registration is already used by another server | Create a separate app registration for each server |
+| Connect or token requests fail with `409 remote_oauth_spec_incoherent` | The McpServer was edited and breaks a rule (reason `scope_audience_mismatch` or `as_profile_issuer_mismatch`) | Fix `spec.oauth.scopes` or `spec.remote.baseUrl`, or reinstall the server |
## Related
diff --git a/docs/llms.txt b/docs/llms.txt
index b1ac1aec3..dae35a5c2 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -39,7 +39,7 @@
- Connect Microsoft Teams (Teams CLI registration, derived endpoint, single-tenant requirement, verify flow): how-to/connect-teams.md
- Use the Desktop App (chat, attachments, EvenDrive, shortcuts, deep links): how-to/use-the-desktop-app.md
- Configure guardrails (rules, installed hooks, built-ins): how-to/configure-guardrails.md
-- Connect an OAuth connector (remote MCP servers, user authorization, connector credentials): how-to/connect-oauth-connector.md
+- Connect an OAuth connector (remote MCP servers, Microsoft 365 / Entra ID, user authorization, connector credentials): how-to/connect-oauth-connector.md
- Configure approvals: how-to/configure-approvals.md
- Add MCP server: how-to/add-mcp-server.md
- Desktop setup & updates (environments, invitation, updates): how-to/desktop-setup-and-updates.md