ctx7-2660: use shared MCP endpoint for EMA

Author: fahreddinozcan

.changeset/ctx7-2660-claude-ema.md

@@ -112,18 +112,20 @@ Use your **org** authorization server issuer (`https://<your-org>.okta.com`), no
 
 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 is configured to use your enterprise IdP for managed connectors.
 
-Your admin connects the Okta org to Claude and enables the dedicated Context7 EMA endpoint as a managed connector:
+Your admin connects the Okta org to Claude and enables the same Context7 endpoint used by the
+Claude Code marketplace plugin as a managed connector:
 
 ```text
-https://mcp.context7.com/mcp/ema
+https://mcp.context7.com/mcp?client=claude-code-plugin
 ```
 
-This URL is intentionally different from the authless `/mcp` endpoint and the interactive OAuth
-`/mcp/oauth` endpoint. It returns an authentication challenge whose protected-resource metadata is
-bound to the full `/mcp/ema` URL and points Claude to Context7's JWT bearer token exchange.
+The `client=claude-code-plugin` query identifies marketplace traffic and makes authentication
+mandatory. It does not select EMA by itself. Claude selects managed authorization when your Claude
+organization enables it for Context7; otherwise Claude Code uses the normal interactive OAuth flow.
+Both flows use the same MCP resource and protected-resource metadata.
 
 After the connector is enabled, Claude obtains an ID-JAG from Okta and exchanges it with Context7
-for a path-bound access token. There is no token to paste and no per-user OAuth consent screen.
+for an access token. There is no token to paste and no per-user OAuth consent screen.
 
 See Claude's
 [Enterprise-Managed Auth for connectors](https://claude.com/docs/connectors/building/enterprise-managed-auth)
@@ -140,9 +142,10 @@ endpoints (`https://<your-org>.okta.com/oauth2/v1/...`).
 
 ### Claude opens an interactive OAuth screen
 
-Confirm that the managed connector URL ends in `/mcp/ema`. The `/mcp/oauth` endpoint is for
-interactive OAuth and advertises a different authorization server. Also confirm that your Claude
-organization has Enterprise-Managed Auth enabled for the connector.
+Confirm that the managed connector URL exactly matches the URL above and that your Claude
+organization has managed authorization enabled for Context7. The query parameter only identifies
+the marketplace plugin; Claude's organization setting determines whether it uses EMA or interactive
+OAuth.
 
 ### A valid Okta user can't be provisioned
 

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

@@ -11,16 +11,14 @@ import {
   extractClientInfoFromUserAgent,
   envelopeClientInfo,
 } from "./lib/utils.js";
-import { isJWT, validateEmaJWT, validateJWT } from "./lib/jwt.js";
+import { isJWT, validateJWT } from "./lib/jwt.js";
 import express from "express";
 import { Command } from "commander";
 import { AsyncLocalStorage } from "async_hooks";
 import { randomUUID } from "node:crypto";
 import {
   SERVER_VERSION,
   RESOURCE_URL,
-  EMA_RESOURCE_METADATA_URL,
-  EMA_RESOURCE_URL,
   OAUTH_AUTH_SERVER_URL,
   EMA_ISSUER,
   OPENAI_APPS_CHALLENGE_TOKEN,
@@ -37,7 +35,7 @@ function getPluginFromRequest(req: express.Request): typeof CLAUDE_CODE_PLUGIN |
 }
 
 function requiresAuthentication(req: express.Request, plugin?: typeof CLAUDE_CODE_PLUGIN): boolean {
-  return req.path === "/mcp/oauth" || req.path === "/mcp/ema" || Boolean(plugin);
+  return req.path === "/mcp/oauth" || Boolean(plugin);
 }
 
 // Parse CLI arguments using commander
@@ -405,17 +403,17 @@ async function main() {
       try {
         const plugin = getPluginFromRequest(req);
         const apiKey = extractApiKey(req);
-        const isEmaRequest = req.path === "/mcp/ema";
-        const resourceMetadataUrl = isEmaRequest
-          ? EMA_RESOURCE_METADATA_URL
-          : `${new URL(RESOURCE_URL).origin}/.well-known/oauth-protected-resource`;
+        const baseUrl = new URL(RESOURCE_URL).origin;
 
         // OAuth discovery info header, used by MCP clients to discover the authorization server
         // TODO: @modelcontextprotocol/server now ships canonical OAuth helpers
         // (bearerAuthChallengeResponse, buildOAuthProtectedResourceMetadata,
         // oauthMetadataResponse) — replace this hand-rolled header and the
         // /.well-known/oauth-protected-resource route with them.
-        res.set("WWW-Authenticate", `Bearer resource_metadata="${resourceMetadataUrl}"`);
+        res.set(
+          "WWW-Authenticate",
+          `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"`
+        );
 
         if (requiresAuthentication(req, plugin)) {
           if (!apiKey) {
@@ -429,18 +427,8 @@ async function main() {
             });
           }
 
-          if (isEmaRequest && !isJWT(apiKey)) {
-            return res.status(401).json({
-              jsonrpc: "2.0",
-              error: { code: -32001, message: "EMA access token required" },
-              id: null,
-            });
-          }
-
           if (isJWT(apiKey)) {
-            const validationResult = isEmaRequest
-              ? await validateEmaJWT(apiKey)
-              : await validateJWT(apiKey);
+            const validationResult = await validateJWT(apiKey);
             if (!validationResult.valid) {
               return res.status(401).json({
                 jsonrpc: "2.0",
@@ -486,13 +474,6 @@ async function main() {
       await handleMcpRequest(req, res);
     });
 
-    // Enterprise-Managed Auth endpoint. It has separate protected-resource
-    // metadata so clients discover Context7's id-jag exchange instead of the
-    // Clerk authorization server used by interactive OAuth.
-    app.all("/mcp/ema", async (req, res) => {
-      await handleMcpRequest(req, res);
-    });
-
     app.get("/ping", (_req: express.Request, res: express.Response) => {
       res.json({ status: "ok", message: "pong" });
     });
@@ -514,18 +495,6 @@ async function main() {
       }
     );
 
-    app.get(
-      "/.well-known/oauth-protected-resource/mcp/ema",
-      (_req: express.Request, res: express.Response) => {
-        res.json({
-          resource: EMA_RESOURCE_URL,
-          authorization_servers: [EMA_ISSUER],
-          scopes_supported: ["profile", "email"],
-          bearer_methods_supported: ["header"],
-        });
-      }
-    );
-
     app.get(
       "/.well-known/oauth-authorization-server",
       async (_req: express.Request, res: express.Response) => {

packages/mcp/src/index.ts

@@ -13,8 +13,6 @@ const DEFAULT_OAUTH_AUTH_SERVER_URL = "https://clerk.context7.com";
 
 export const CONTEXT7_API_BASE_URL = process.env.CONTEXT7_API_URL || `${CONTEXT7_BASE_URL}/api`;
 export const RESOURCE_URL = process.env.RESOURCE_URL || MCP_RESOURCE_URL;
-export const EMA_RESOURCE_URL = `${MCP_RESOURCE_URL}/mcp/ema`;
-export const EMA_RESOURCE_METADATA_URL = `${MCP_RESOURCE_URL}/.well-known/oauth-protected-resource/mcp/ema`;
 
 // Clerk owns the interactive OAuth flow and is the issuer returned in the
 // authorization response. Advertising Clerk directly keeps RFC 8414 discovery

packages/mcp/src/lib/constants.ts

@@ -3,9 +3,9 @@ import {
   CONTEXT7_API_BASE_URL,
   EMA_ISSUER,
   EMA_JWKS_URL,
-  EMA_RESOURCE_URL,
   OAUTH_AUTH_SERVER_URL,
   OAUTH_JWKS_URL,
+  RESOURCE_URL,
 } from "./constants.js";
 
 const oauthJwks = jose.createRemoteJWKSet(new URL(OAUTH_JWKS_URL));
@@ -71,24 +71,6 @@ export function isJWT(token: string): boolean {
   return token.split(".").length === 3;
 }
 
-export async function validateEmaJWT(token: string): Promise<JWTValidationResult> {
-  try {
-    await jose.jwtVerify(token, emaJwks, { issuer: EMA_ISSUER, audience: EMA_RESOURCE_URL });
-    return { valid: true };
-  } catch (error) {
-    if (error instanceof jose.errors.JWTExpired) {
-      return { valid: false, error: "Token expired" };
-    }
-    if (error instanceof jose.errors.JWTClaimValidationFailed) {
-      return { valid: false, error: "Invalid token claims" };
-    }
-    if (error instanceof jose.errors.JWSSignatureVerificationFailed) {
-      return { valid: false, error: "Invalid signature" };
-    }
-    return { valid: false, error: "Invalid token" };
-  }
-}
-
 export async function validateJWT(token: string): Promise<JWTValidationResult> {
   try {
     const decoded = jose.decodeJwt(token);
@@ -117,7 +99,7 @@ export async function validateJWT(token: string): Promise<JWTValidationResult> {
     }
 
     if (iss === EMA_ISSUER) {
-      await jose.jwtVerify(token, emaJwks, { issuer: EMA_ISSUER, audience: EMA_RESOURCE_URL });
+      await jose.jwtVerify(token, emaJwks, { issuer: EMA_ISSUER, audience: RESOURCE_URL });
       return { valid: true };
     }
 

packages/mcp/src/lib/jwt.ts

@@ -160,48 +160,6 @@ describe("OAuth discovery", () => {
       authorization_servers: ["https://clerk.context7.com", "https://context7.com"],
     });
   });
-
-  test("advertises only the EMA issuer for the path-bound EMA resource", async () => {
-    const metadataUrl = new URL("/.well-known/oauth-protected-resource/mcp/ema", httpUrl);
-    const response = await fetch(metadataUrl);
-
-    expect(response.status).toBe(200);
-    expect(await response.json()).toEqual({
-      resource: "https://mcp.context7.com/mcp/ema",
-      authorization_servers: ["https://context7.com"],
-      scopes_supported: ["profile", "email"],
-      bearer_methods_supported: ["header"],
-    });
-  });
-
-  test("challenges unauthenticated EMA requests with the path-bound metadata URL", async () => {
-    const response = await fetch(new URL("/mcp/ema", httpUrl), {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: "{}",
-    });
-
-    expect(response.status).toBe(401);
-    expect(response.headers.get("www-authenticate")).toBe(
-      'Bearer resource_metadata="https://mcp.context7.com/.well-known/oauth-protected-resource/mcp/ema"'
-    );
-  });
-
-  test("rejects opaque bearer credentials on the EMA endpoint", async () => {
-    const response = await fetch(new URL("/mcp/ema", httpUrl), {
-      method: "POST",
-      headers: {
-        authorization: "Bearer not-an-ema-token",
-        "content-type": "application/json",
-      },
-      body: "{}",
-    });
-
-    expect(response.status).toBe(401);
-    expect(await response.json()).toMatchObject({
-      error: { message: "EMA access token required" },
-    });
-  });
 });
 
 describe("HTTP API key headers", () => {

packages/mcp/test/integration.test.ts

@@ -58,24 +58,6 @@ afterEach(() => {
   vi.clearAllMocks();
 });
 
-describe("validateJWT - EMA path", () => {
-  test("requires the EMA issuer and path-bound resource", async () => {
-    vi.mocked(jose.jwtVerify).mockResolvedValue({
-      payload: {},
-      protectedHeader: { alg: "RS256" },
-    } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);
-
-    const { validateEmaJWT } = await loadModule();
-    const result = await validateEmaJWT(makeEntraToken({ iss: "https://clerk.context7.com" }));
-
-    expect(result.valid).toBe(true);
-    expect(jose.jwtVerify).toHaveBeenCalledWith(expect.any(String), "fake-jwks", {
-      issuer: "https://context7.com",
-      audience: "https://mcp.context7.com/mcp/ema",
-    });
-  });
-});
-
 describe("isJWT", () => {
   test("returns true for 3-part dotted strings", async () => {
     const { isJWT } = await loadModule();
@@ -195,6 +177,24 @@ describe("validateJWT - Entra path", () => {
   });
 });
 
+describe("validateJWT - EMA path", () => {
+  test("verifies Context7-issued tokens for the shared MCP resource", async () => {
+    vi.mocked(jose.jwtVerify).mockResolvedValue({
+      payload: {},
+      protectedHeader: { alg: "RS256" },
+    } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);
+
+    const { validateJWT } = await loadModule();
+    const result = await validateJWT(makeEntraToken({ iss: "https://context7.com" }));
+
+    expect(result.valid).toBe(true);
+    expect(jose.jwtVerify).toHaveBeenCalledWith(expect.any(String), "fake-jwks", {
+      issuer: "https://context7.com",
+      audience: "https://mcp.context7.com",
+    });
+  });
+});
+
 describe("validateJWT - Clerk path", () => {
   test("verifies against Clerk JWKS for non-Entra issuers", async () => {
     vi.mocked(jose.jwtVerify).mockResolvedValue({