feat(mcp): Enterprise-Managed Auth (id-jag) validation + Okta docs (#2798)

* feat(mcp): Enterprise-Managed Auth (id-jag) validation + Okta docs

* docs(enterprise): clarify Okta connection is client-side org config, drop wrong client JSON

* docs(enterprise): remove em dashes

* docs(enterprise): group Entra and Okta under Enterprise-Managed Auth, redirect old azure-apim path

* refactor docs

---------

Co-authored-by: enesgules <abdullah.enes.gules@gmail.com>

Author: fahreddinozcan

.changeset/enterprise-managed-auth-okta.md

@@ -0,0 +1,5 @@
+---
+"@upstash/context7-mcp": patch
+---
+
+Validate Enterprise-Managed Auth (id-jag) access tokens at the MCP server, so MCP clients can authenticate to Context7 through an enterprise IdP (Okta) via the MCP Enterprise-Managed Authorization extension.

docs/docs.json

@@ -3,6 +3,12 @@
   "theme": "mint",
   "name": "Context7 MCP",
   "description": "Up-to-date code docs for any prompt.",
+  "redirects": [
+    {
+      "source": "/enterprise/azure-apim",
+      "destination": "/enterprise/enterprise-managed-auth/entra"
+    }
+  ],
   "colors": {
     "primary": "#10B981",
     "light": "#ECFDF5",
@@ -56,7 +62,13 @@
         "group": "Enterprise",
         "pages": [
           "enterprise",
-          "enterprise/azure-apim",
+          {
+            "group": "Enterprise-Managed Auth",
+            "pages": [
+              "enterprise/enterprise-managed-auth/entra",
+              "enterprise/enterprise-managed-auth/okta"
+            ]
+          },
           {
             "group": "On-Premise",
             "pages": [

docs/enterprise/azure-apim.mdx …rprise/enterprise-managed-auth/entra.mdxdocs/enterprise/azure-apim.mdx renamed to docs/enterprise/enterprise-managed-auth/entra.mdx docs/enterprise/azure-apim.mdx renamed to docs/enterprise/enterprise-managed-auth/entra.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Azure API Management as MCP gateway"
-sidebarTitle: "Azure APIM"
+sidebarTitle: "Microsoft Entra ID"
 description: "Route Context7 MCP traffic through Azure API Management with per-user Microsoft Entra ID authentication."
 ---
 
@@ -159,7 +159,7 @@ This app represents the gateway as an Entra resource. Clients request tokens for
 7. **Authentication** → **+ Add a platform** → **Web** → enter `https://vscode.dev/redirect` as the redirect URI → **Configure**.
 
    <Note>
-   VS Code with GitHub Copilot uses Microsoft's hosted OAuth broker at `vscode.dev/redirect` rather than a local loopback URI. The redirect URI must be registered on the Gateway app or the sign-in flow fails with `AADSTS500113` or `AADSTS50011`. Add additional redirect URIs (or platforms) here for other MCP clients as you adopt them — each client tool's documentation lists its expected URI.
+   VS Code with GitHub Copilot uses Microsoft's hosted OAuth broker at `vscode.dev/redirect` rather than a local loopback URI. The redirect URI must be registered on the Gateway app or the sign-in flow fails with `AADSTS500113` or `AADSTS50011`. Add additional redirect URIs (or platforms) here for other MCP clients as you adopt them. Each client tool's documentation lists its expected URI.
    </Note>
 
 ### Step 3: Wire the permission chain
@@ -347,7 +347,7 @@ The cache duration (`3000` seconds) is slightly below Entra's default access tok
 
 ## Part 4: Onboard your tenant in Context7
 
-Context7 validates inbound tokens in two stages: first the token's signature, audience, issuer, and scope are checked against your teamspace's tenant configuration; then the token's `oid` claim is resolved against a list of pre-provisioned users for the teamspace. **Both checks are mandatory** — any developer who has not been added to the teamspace's user list will be rejected with `401` even when their token is otherwise valid.
+Context7 validates inbound tokens in two stages: first the token's signature, audience, issuer, and scope are checked against your teamspace's tenant configuration; then the token's `oid` claim is resolved against a list of pre-provisioned users for the teamspace. **Both checks are mandatory.** Any developer who has not been added to the teamspace's user list will be rejected with `401` even when their token is otherwise valid.
 
 An owner or admin of the teamspace configures both from the dashboard. Users can be added one at a time (Step 2) or synced automatically from an Entra security group (Step 3).
 
@@ -361,9 +361,9 @@ An owner or admin of the teamspace configures both from the dashboard. Users can
    </Note>
 
 3. Fill in:
-   - **Tenant ID** — your Entra directory ID
-   - **Audience** — the **MCP API app** Application (client) ID (the second token's audience, not the gateway app)
-   - **Required scope** — `mcp.access`
+   - **Tenant ID:** your Entra directory ID
+   - **Audience:** the **MCP API app** Application (client) ID (the second token's audience, not the gateway app)
+   - **Required scope:** `mcp.access`
 
 4. Click **Test connection**. Context7 fetches your tenant's OpenID Connect discovery document from Microsoft and confirms the issuer matches.
 
@@ -375,45 +375,45 @@ After saving the tenant configuration, scroll down to the **Microsoft Entra ID u
 
 1. Click **Add user**.
 2. Enter the user's:
-   - **Email** — the address they sign in to Entra with.
-   - **Object ID (oid)** — their Entra object ID. Find it in the Entra admin center under **Users → `<name>` → Overview → Object ID**, or have the user run `az ad signed-in-user show --query id -o tsv` after `az login`.
+   - **Email:** the address they sign in to Entra with.
+   - **Object ID (oid):** their Entra object ID. Find it in the Entra admin center under **Users → `<name>` → Overview → Object ID**, or have the user run `az ad signed-in-user show --query id -o tsv` after `az login`.
 3. Click **Add user** to save.
 
-Context7 creates a Clerk user record for the developer, adds them as a `developer` member of the teamspace, and inserts a `(tenant, oid, teamspace)` mapping. The same email can be added to multiple teamspaces — the Clerk user is reused and a separate mapping row is created per teamspace.
+Context7 creates a Clerk user record for the developer, adds them as a `developer` member of the teamspace, and inserts a `(tenant, oid, teamspace)` mapping. The same email can be added to multiple teamspaces; the Clerk user is reused and a separate mapping row is created per teamspace.
 
 <Note>
 Clicking **Remove** on the Microsoft Entra ID card removes both the tenant configuration **and** all provisioned users for the teamspace in a single step. If you only need to revoke a single user, remove them from the Microsoft Entra ID users card instead.
 </Note>
 
 <Note>
-Each MCP API app (audience) can be configured for **one** teamspace at a time. If you reuse an audience already claimed by a different teamspace you will see "This audience is already configured for another teamspace" — open the other teamspace's Settings tab and remove the Entra configuration there first, or register a new MCP API app for this teamspace.
+Each MCP API app (audience) can be configured for **one** teamspace at a time. If you reuse an audience already claimed by a different teamspace you will see "This audience is already configured for another teamspace". Open the other teamspace's Settings tab and remove the Entra configuration there first, or register a new MCP API app for this teamspace.
 </Note>
 
 <Note>
-For more than a handful of developers, prefer **Step 3: Auto-provision from an Entra security group** below — adds and revokes track group membership automatically. CSV bulk-import and SCIM provisioning remain on the roadmap; reach out to [context7@upstash.com](mailto:context7@upstash.com) if your scale needs either ahead of general availability.
+For more than a handful of developers, prefer **Step 3: Auto-provision from an Entra security group** below. Adds and revokes track group membership automatically. CSV bulk-import and SCIM provisioning remain on the roadmap; reach out to [context7@upstash.com](mailto:context7@upstash.com) if your scale needs either ahead of general availability.
 </Note>
 
 ### Step 3: Auto-provision from an Entra security group (optional)
 
 For teams of more than a handful of developers, Context7 can sync the teamspace's user list directly from a Microsoft Entra security group. Members added to the group are added to the teamspace automatically; members removed from the group have their access revoked. The sync runs every 30 minutes; an admin can also trigger an immediate sync from the dashboard.
 
-The integration uses Microsoft Graph with **Workload Identity Federation** (WIF) — Context7 acts as an OIDC issuer and signs short-lived JWT assertions that your sync app trusts via a federated credential. No shared secret is stored, rotated, or exchanged on either side.
+The integration uses Microsoft Graph with **Workload Identity Federation** (WIF). Context7 acts as an OIDC issuer and signs short-lived JWT assertions that your sync app trusts via a federated credential. No shared secret is stored, rotated, or exchanged on either side.
 
 1. **Add Microsoft Graph permissions** to an Entra app registration.
 
-   The simplest path is to reuse the **Context7 MCP API** app from [Part 2 Step 1](#step-1-register-the-mcp-api-app) — federated identity holds no secret, so reusing it adds no risk. Open that app and add:
+   The simplest path is to reuse the **Context7 MCP API** app from [Part 2 Step 1](#step-1-register-the-mcp-api-app): federated identity holds no secret, so reusing it adds no risk. Open that app and add:
 
    - **API permissions** → **+ Add a permission** → **Microsoft Graph** → **Application permissions**.
    - Search and tick `GroupMember.Read.All` and `User.ReadBasic.All`.
    - **Add permissions**, then click **Grant admin consent for `<your tenant>`** at the top of the list.
 
    <Note>
-   Both permissions are required. `GroupMember.Read.All` alone returns each user's `oid` with all profile fields nulled out, so the sync can't resolve them to emails and drops them — surfacing as `0 members` synced. `User.ReadBasic.All` populates `mail`, `userPrincipalName`, and `displayName`.
+   Both permissions are required. `GroupMember.Read.All` alone returns each user's `oid` with all profile fields nulled out, so the sync can't resolve them to emails and drops them, surfacing as `0 members` synced. `User.ReadBasic.All` populates `mail`, `userPrincipalName`, and `displayName`.
    </Note>
 
 2. **Add a federated credential.**
 
-   On the same app: **Certificates & secrets** → **Federated credentials** tab → **+ Add credential** → **Federated credential scenario: Other issuer**. Open the Context7 dashboard alongside the Entra portal — the **Auto-provisioning from Entra group** card surfaces three values with copy buttons. Paste them as:
+   On the same app: **Certificates & secrets** → **Federated credentials** tab → **+ Add credential** → **Federated credential scenario: Other issuer**. Open the Context7 dashboard alongside the Entra portal. The **Auto-provisioning from Entra group** card surfaces three values with copy buttons. Paste them as:
 
    - **Issuer**: `https://context7.com`
    - **Type**: Explicit subject identifier
@@ -425,7 +425,7 @@ The integration uses Microsoft Graph with **Workload Identity Federation** (WIF)
 
 3. **Create or pick an Entra security group** containing the developers who should have access.
 
-   Entra admin center → **Groups** → **+ New group** (type *Security*, membership type *Assigned*). Add developers as **Members**, not Owners — Graph's `/members` endpoint doesn't include group owners by default.
+   Entra admin center → **Groups** → **+ New group** (type *Security*, membership type *Assigned*). Add developers as **Members**, not Owners. Graph's `/members` endpoint doesn't include group owners by default.
 
    Open the group → **Overview** → copy the **Object ID**.
 
@@ -446,7 +446,7 @@ Manually-added users (Step 2) and synced users (Step 3) coexist on the same team
 </Note>
 
 <Note>
-If you want strict separation of concerns, register a dedicated **Context7 Sync** app instead of reusing the MCP API app. Add the same two Graph permissions and the same federated credential to it, and use its client ID in step 4. The choice is purely organizational — both produce identical sync behavior.
+If you want strict separation of concerns, register a dedicated **Context7 Sync** app instead of reusing the MCP API app. Add the same two Graph permissions and the same federated credential to it, and use its client ID in step 4. The choice is purely organizational; both produce identical sync behavior.
 </Note>
 
 <Note>

docs/enterprise/enterprise-managed-auth/okta.mdx

@@ -0,0 +1,129 @@
+---
+title: "Enterprise-Managed Auth with Okta"
+sidebarTitle: "Okta"
+description: "Centrally authorize the Context7 MCP server for your organization through Okta Cross-App Access, so developers connect on first login with no per-user OAuth."
+---
+
+Enterprise-Managed Auth (EMA) lets your Okta administrators decide who can use the Context7 MCP server, in the same console where you manage every other app. Developers sign in once with their corporate Okta account and their MCP client is connected automatically. There is no per-user OAuth consent and no API keys to distribute.
+
+It implements the MCP [Enterprise-Managed Authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) extension: Okta issues a short-lived Identity Assertion (ID-JAG) for the user, Context7 validates it against your Okta tenant, and resolves the user to your teamspace by email.
+
+<Warning>
+Enterprise-Managed Auth currently works with **Claude Code** as the MCP client.
+</Warning>
+
+<Note>
+Okta Cross-App Access (the productized ID-JAG flow) is an Early Access feature. Enable it from **Admin Console → Settings → Features** before you start. EMA also requires a Context7 enterprise teamspace.
+</Note>
+
+## How it works
+
+- A developer signs in to their MCP client with your Okta org.
+- The client asks Okta for an ID-JAG scoped to Context7. Okta applies your access policy (group, role, conditional access) and issues it only if the user is allowed.
+- The client exchanges the ID-JAG with Context7 for an access token, then calls `mcp.context7.com`.
+- Context7 validates the ID-JAG against your tenant and, on first sign-in, provisions the user as a teamspace member automatically (matched by email).
+
+Access is governed entirely in Okta. There is no user list to maintain in Context7: anyone your admin assigns to the connected app is provisioned on first sign-in. Removing them from the app blocks new sign-ins immediately, and any active session ends when its short-lived access token expires (within an hour).
+
+## Before you start
+
+- An **Okta org** with **Cross App Access** enabled.
+- A **Context7 enterprise teamspace**. The Enterprise-Managed Auth settings appear only for enterprise plans.
+- Developers assigned to the connected Okta app. They are provisioned into the teamspace automatically on first sign-in, so there is no manual user list to maintain.
+
+## Part 1: Configure Okta
+
+### Step 1: Enable Cross App Access
+
+In the **Admin Console**, go to **Settings → Features**, find **Cross App Access** under Early Access, and turn it on.
+
+<Frame>
+  ![Cross App Access toggle in Okta Admin Console Settings → Features](/images/enterprise/enterprise-managed-auth/okta-enable-feature.png)
+</Frame>
+
+### Step 2: Add Context7 as a resource app
+
+Go to **Applications → Applications → Browse App Catalog**, search for **XAA Resource App**, and click **Add Integration**.
+
+- **Application label:** `Context7`
+- **Issuer URL:** `https://context7.com`
+
+Click **Done**.
+
+<Frame>
+  ![Add XAA Resource App general settings with Context7 label and issuer URL](/images/enterprise/enterprise-managed-auth/okta-resource-app.png)
+</Frame>
+
+### Step 3: Add your MCP client as a requesting app
+
+Browse the catalog again, search for **XAA Requesting App**, and click **Add Integration**.
+
+- **Application label:** a name for the MCP client (for example `MCP Client`)
+- **Issuer URL:** `https://context7.com`
+- **Client ID:** the client identifier the MCP client uses (for example `mcpclient-at-context7`)
+
+Click **Done**, then open the **Sign On** tab and note the Client ID and secret if your client needs them.
+
+<Frame>
+  ![Add XAA Requesting App general settings with label, issuer URL, and client ID](/images/enterprise/enterprise-managed-auth/okta-requesting-app.png)
+</Frame>
+
+### Step 4: Connect the two apps
+
+Open the requesting app → **Manage Connections** tab. Under **Apps providing consent**, choose **Add resource apps**, select **Context7**, and **Save**.
+
+<Frame>
+  ![Manage Connections tab linking the MCP Client to the Context7 resource app](/images/enterprise/enterprise-managed-auth/okta-manage-connections.png)
+</Frame>
+
+### Step 5: Assign your users
+
+On both apps, open the **Assignments** tab and assign the people (or groups) who should have access. Only assigned users can obtain an ID-JAG.
+
+<Frame>
+  ![Assignments tab assigning a user to the app](/images/enterprise/enterprise-managed-auth/okta-assignments.png)
+</Frame>
+
+## Part 2: Configure Context7
+
+Sign in to [context7.com/dashboard](https://context7.com/dashboard), select your enterprise teamspace, open the **Enterprise** tab, and select **Okta**.
+
+- **Identity provider issuer:** your Okta org issuer, for example `https://<your-org>.okta.com`.
+- **Scope** (optional): scopes to grant on the issued access token. Leave blank to pass through whatever Okta authorizes.
+
+Click **Configure**, enter the issuer, and **Save**. Context7 validates the issuer against your tenant's OpenID Connect metadata on save.
+
+<Frame>
+  ![Context7 dashboard Enterprise-Managed Auth settings card with the Okta issuer field](/images/enterprise/enterprise-managed-auth/context7-ema-config.png)
+</Frame>
+
+<Note>
+Use your **org** authorization server issuer (`https://<your-org>.okta.com`), not a custom authorization server. Cross-App Access apps cannot use custom authorization servers.
+</Note>
+
+## Part 3: How developers connect
+
+Enterprise-Managed Auth is wired on the **client** side by your organization, not per developer. The Okta sign-in isn't triggered by a server URL someone pastes. It happens because Claude Code is configured to use your enterprise IdP for managed connectors.
+
+Your admin connects the Okta org to Claude and enables the Context7 MCP server (`https://mcp.context7.com/mcp`) as a managed connector. After that, anyone using Claude Code with their corporate Okta identity gets Context7 automatically: Claude Code obtains an ID-JAG from Okta and exchanges it with Context7 for an access token. There is no token to paste and no per-user OAuth.
+
+See Claude's [Enterprise-Managed Auth](https://claude.com/blog/enterprise-managed-auth) documentation for the client-side admin setup.
+
+## Troubleshooting
+
+### `unauthorized_client` / "client cannot use a custom authorization server"
+
+The sign-in or token-exchange used a custom authorization server. Use the org authorization server endpoints (`https://<your-org>.okta.com/oauth2/v1/...`).
+
+### A valid Okta user can't be provisioned
+
+Context7 provisions members from the `email` claim on the ID-JAG, so the connected app must request the `email` scope at sign-in (it's included in the setup above). If provisioning still fails, the teamspace may be at its member limit.
+
+### The user receives no token at all
+
+The user is not assigned to the connected apps in Okta, or the connection between the requesting and resource apps was not saved. Re-check Steps 4 and 5.
+
+## What this does not cover
+
+- **Identity providers other than Okta.** EMA currently supports Okta as the IdP. For Microsoft Entra, see [Microsoft Entra ID](/enterprise/enterprise-managed-auth/entra).
+- **Group-based authorization inside Context7.** Okta decides who can obtain a token; Context7 authorizes against teamspace membership. Restricting which libraries a group can access is not configured here.