feat(mcp): guest + anonymous access to the platform MCP server (#2675)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: chelojimenez

mcp/src/auth.ts

@@ -11,6 +11,16 @@ export interface VerifiedToken {
   payload: JWTPayload;
 }
 
+/**
+ * Guest token issuer. Mirrors the inspector's
+ * `server/services/guest-token-keypair.ts` and the backend's
+ * `convex/lib/guestJwt.ts` (`GUEST_ISSUER`). Guest tokens are RS256, carry
+ * `{ iss, sub, iat, exp }` with NO `aud` claim, and must NOT carry a
+ * `purpose` claim (promotion-proof tokens must not double as session
+ * bearers — see `verifyGuestBearerToken` in the backend).
+ */
+export const GUEST_ISSUER = "https://api.mcpjam.com/guest";
+
 export type VerifyResult =
   | { ok: true; verified: VerifiedToken }
   | { ok: false; response: Response };
@@ -87,11 +97,24 @@ export interface VerifyConfig {
   clientId: string;
   /** Custom AuthKit domain (`env.AUTHKIT_DOMAIN`), added to the issuer set. */
   authkitDomain: string | undefined;
+  /**
+   * Guest verification. When set, a token whose `iss` equals `guest.issuer`
+   * is verified against `guest.jwksUrl` (the JWKS the platform publishes for
+   * guest tokens) with NO audience pin. When undefined, guest tokens are
+   * rejected (the guest issuer is absent from the AuthKit allow-list).
+   */
+  guest?: { issuer: string; jwksUrl: string };
   /**
    * Issuer → key/JWKS resolver. `null` rejects the issuer. Injectable for
    * tests; production derives it from the allow-list above (remote JWKS).
    */
   resolveKey?: (issuer: string) => KeyResolver | null;
+  /**
+   * Guest key resolver, parallel to `resolveKey`. Injectable for tests so the
+   * guest branch doesn't need a remote JWKS; production resolves the remote
+   * JWKS at `guest.jwksUrl`.
+   */
+  resolveGuestKey?: (issuer: string) => KeyResolver | null;
 }
 
 function defaultResolveKey(
@@ -152,6 +175,16 @@ export async function verifyBearerToken(
     return { ok: false, response: invalidTokenResponse(origin) };
   }
 
+  // Guest branch: a guest token (`iss === guest.issuer`) is verified against
+  // the guest JWKS with NO audience pin (guest tokens carry no `aud`). Checked
+  // before the AuthKit path because the guest issuer is intentionally absent
+  // from `authkitIssuerJwks`. The trust decision is still `jwtVerify` —
+  // signature + issuer pin + RS256 + exp — plus an explicit `purpose`
+  // rejection mirroring the backend's `verifyGuestBearerToken`.
+  if (config.guest && issuer === config.guest.issuer) {
+    return verifyGuestToken(token, issuer, config, origin);
+  }
+
   const resolveKey =
     config.resolveKey ?? defaultResolveKey(config.clientId, config.authkitDomain);
   const key = resolveKey(issuer);
@@ -176,6 +209,47 @@ export async function verifyBearerToken(
   }
 }
 
+async function verifyGuestToken(
+  token: string,
+  issuer: string,
+  config: VerifyConfig,
+  origin: string,
+): Promise<VerifyResult> {
+  const guest = config.guest;
+  if (!guest) {
+    return { ok: false, response: invalidTokenResponse(origin) };
+  }
+  const key = config.resolveGuestKey
+    ? config.resolveGuestKey(issuer)
+    : remoteJwks(guest.jwksUrl);
+  if (!key) {
+    return { ok: false, response: invalidTokenResponse(origin) };
+  }
+  const getKey: JWTVerifyGetKey =
+    typeof key === "function" ? (key as JWTVerifyGetKey) : async () => key;
+
+  try {
+    const { payload } = await jwtVerify(token, getKey, {
+      issuer: guest.issuer,
+      // No `audience`: guest tokens carry no `aud` claim.
+      algorithms: ["RS256"],
+      clockTolerance: 5,
+    });
+    // Mirror the backend's `verifyGuestBearerToken`: session bearers never
+    // carry a `purpose` (promotion-proof tokens do), and must have a non-empty
+    // string `sub`.
+    if (payload.purpose !== undefined) {
+      return { ok: false, response: invalidTokenResponse(origin) };
+    }
+    if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+      return { ok: false, response: invalidTokenResponse(origin) };
+    }
+    return { ok: true, verified: { token, payload } };
+  } catch {
+    return { ok: false, response: invalidTokenResponse(origin) };
+  }
+}
+
 export const OAUTH_DISCOVERY_HEADERS = {
   "access-control-allow-origin": "*",
   "access-control-expose-headers": "WWW-Authenticate",

mcp/src/env.d.ts

@@ -0,0 +1,21 @@
+// Secrets live outside `wrangler.jsonc` vars (set via `wrangler secret put`),
+// so `wrangler types` does not emit them into `worker-configuration.d.ts`.
+// Declaration-merge them onto the global `Env` here so they survive type
+// regeneration.
+interface Env {
+  /**
+   * Shared secret presented to the inspector guest-mint route as
+   * `x-inspector-service-token` (matches the inspector's
+   * `INSPECTOR_SERVICE_TOKEN`). Set with `wrangler secret put
+   * MCPJAM_INSPECTOR_SERVICE_TOKEN --env <env>`.
+   */
+  MCPJAM_INSPECTOR_SERVICE_TOKEN?: string;
+
+  /**
+   * Killswitch toggle (runtime var / dashboard secret, not in wrangler.jsonc).
+   * When "true", the worker is AuthKit-only: guest tokens are rejected and
+   * anonymous (tokenless) /mcp connections get the normal 401 → OAuth
+   * challenge.
+   */
+  MCPJAM_NONPROD_LOCKDOWN?: string;
+}

mcp/src/index.ts

@@ -1,8 +1,10 @@
 import { McpJamMcpServer } from "./server.js";
 import {
+  GUEST_ISSUER,
   OAUTH_DISCOVERY_HEADERS,
   normalizeIssuer,
   verifyBearerToken,
+  type VerifyConfig,
 } from "./auth.js";
 
 export { McpJamMcpServer };
@@ -115,20 +117,63 @@ export default {
         return McpJamMcpServer.serve("/mcp").fetch(request, env, ctx);
       }
 
-      const result = await verifyBearerToken(
-        request,
-        { clientId, authkitDomain: env.AUTHKIT_DOMAIN },
-        origin,
-      );
-      if (!result.ok) return result.response;
+      // Killswitch: when locked down, the server is AuthKit-only — guest
+      // tokens are not accepted and anonymous (tokenless) connections are
+      // refused with the normal 401 → OAuth challenge.
+      const lockedDown = env.MCPJAM_NONPROD_LOCKDOWN === "true";
+
+      // Guest verification is enabled only when a guest JWKS URL is configured
+      // (and not locked down). Absent it, guest tokens fall through to the
+      // AuthKit allow-list and are rejected.
+      const guest: VerifyConfig["guest"] =
+        !lockedDown && env.MCPJAM_GUEST_JWKS_URL
+          ? { issuer: GUEST_ISSUER, jwksUrl: env.MCPJAM_GUEST_JWKS_URL }
+          : undefined;
+
+      let props: { bearerToken?: string; claims?: unknown; clientIp?: string };
+      if (request.headers.has("authorization")) {
+        // A bearer was presented → it must verify (AuthKit or guest). A
+        // present-but-invalid token still 401s; we never downgrade it to an
+        // anonymous guest.
+        const result = await verifyBearerToken(
+          request,
+          { clientId, authkitDomain: env.AUTHKIT_DOMAIN, guest },
+          origin,
+        );
+        if (!result.ok) return result.response;
+        props = {
+          bearerToken: result.verified.token,
+          claims: result.verified.payload,
+        };
+      } else if (lockedDown) {
+        // Tokenless + locked down → preserve the 401 → OAuth challenge.
+        const result = await verifyBearerToken(
+          request,
+          { clientId, authkitDomain: env.AUTHKIT_DOMAIN },
+          origin,
+        );
+        // verifyBearerToken returns the 401 missing-token response here.
+        if (!result.ok) return result.response;
+        props = {
+          bearerToken: result.verified.token,
+          claims: result.verified.payload,
+        };
+      } else {
+        // Tokenless anonymous session: NO mint here. The Durable Object mints
+        // a guest token lazily on first platform-tool execution. Capture the
+        // edge-provided client IP (trustworthy here — set by Cloudflare on the
+        // inbound hit) so the DO can forward it to the rate-limited mint route.
+        props = {
+          bearerToken: undefined,
+          claims: undefined,
+          clientIp: request.headers.get("cf-connecting-ip") ?? undefined,
+        };
+      }
 
       const authedCtx: ExecutionContext<Record<string, unknown>> = {
         waitUntil: (promise: Promise<unknown>) => ctx.waitUntil(promise),
         passThroughOnException: () => ctx.passThroughOnException(),
-        props: {
-          bearerToken: result.verified.token,
-          claims: result.verified.payload,
-        },
+        props,
       };
 
       return McpJamMcpServer.serve("/mcp").fetch(request, env, authedCtx);

mcp/src/server.ts

@@ -11,12 +11,25 @@ import { registerPlatformCatalogTools } from "./tools/platformTools.js";
 import { registerShowServersTool } from "./tools/showServers.js";
 
 interface McpProps extends Record<string, unknown> {
-  bearerToken: string;
-  claims: JWTPayload;
+  // Optional: an anonymous (tokenless) session carries neither. The bearer is
+  // then minted lazily on first platform-tool execution (see getBearerToken).
+  bearerToken?: string;
+  claims?: JWTPayload;
+  // Real client IP for the anonymous connection (set by the edge from
+  // cf-connecting-ip), forwarded to the mint route so it can rate-limit per
+  // client rather than per worker.
+  clientIp?: string;
 }
 
+// Re-mint a minted guest token this far before its expiry. A guest token is
+// long-lived (~24h) but a long-running anonymous session must not start
+// failing every tool call the moment it lapses — refresh ahead of the edge.
+const GUEST_TOKEN_REFRESH_SLACK_MS = 60_000;
+
 export class McpJamMcpServer extends McpAgent<Env, unknown, McpProps> {
   private sessionToolRegistrar?: SessionToolRegistrar;
+  private mintedGuest?: { token: string; expiresAt: number };
+  private mintInFlight?: Promise<string | undefined>;
 
   server = new McpServer({
     name: "MCPJam MCP",
@@ -27,8 +40,43 @@ export class McpJamMcpServer extends McpAgent<Env, unknown, McpProps> {
     return this.env as Required<Env>;
   }
 
+  /** Synchronous view: the verified/minted token if one already exists. */
   get bearerToken(): string | undefined {
-    return this.props?.bearerToken;
+    return this.props?.bearerToken ?? this.mintedGuest?.token;
+  }
+
+  /**
+   * The bearer to authenticate Platform API calls with. For an authed session
+   * it's the verified token. For an anonymous session it's a guest token
+   * minted lazily on first call (NOT at connect/list_tools — listing tools
+   * needs no Platform API, so an anonymous preflight must not create a guest
+   * session) and re-minted before it expires, so a long-lived session never
+   * starts 401ing on a lapsed guest token. Concurrent calls share one mint; a
+   * mint failure surfaces as a tool error (caller checks for undefined) and is
+   * retried next call.
+   */
+  async getBearerToken(): Promise<string | undefined> {
+    if (this.props?.bearerToken) return this.props.bearerToken;
+
+    const cached = this.mintedGuest;
+    if (cached && cached.expiresAt - Date.now() > GUEST_TOKEN_REFRESH_SLACK_MS) {
+      return cached.token;
+    }
+
+    // Absent or within the refresh window → (re)mint once, shared across
+    // concurrent callers.
+    if (!this.mintInFlight) {
+      this.mintInFlight = mintGuestToken(this.env, this.props?.clientIp)
+        .then((minted) => {
+          this.mintedGuest = minted; // undefined on failure → cache untouched
+          return minted?.token;
+        })
+        .catch(() => undefined)
+        .finally(() => {
+          this.mintInFlight = undefined; // allow refresh/retry next call
+        });
+    }
+    return this.mintInFlight;
   }
 
   async init(): Promise<void> {
@@ -88,6 +136,61 @@ export class McpJamMcpServer extends McpAgent<Env, unknown, McpProps> {
   }
 }
 
+/**
+ * Mint a fresh guest token via the inspector's service-token-gated route
+ * (`MCPJAM_GUEST_MINT_URL`). The route mints through the same Convex authority
+ * that publishes the guest JWKS the worker verifies against, so the token is
+ * accepted on the way back in. The client IP is forwarded in a custom header
+ * (cf-connecting-ip would be overwritten by Cloudflare on the worker→inspector
+ * hop) so the route can rate-limit per client. Returns the token and its
+ * expiry (ms epoch) so the session can refresh before it lapses; returns
+ * undefined on any failure (the caller turns that into a tool error).
+ */
+async function mintGuestToken(
+  env: Env,
+  clientIp: string | undefined
+): Promise<{ token: string; expiresAt: number } | undefined> {
+  const url = env.MCPJAM_GUEST_MINT_URL;
+  const serviceToken = env.MCPJAM_INSPECTOR_SERVICE_TOKEN;
+  if (!url || !serviceToken) return undefined;
+  try {
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "x-inspector-service-token": serviceToken,
+    };
+    if (clientIp) headers["x-mcpjam-client-ip"] = clientIp;
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: "{}",
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return undefined;
+    const data = (await response.json()) as {
+      token?: unknown;
+      expiresAt?: unknown;
+    };
+    if (typeof data.token !== "string") return undefined;
+    return { token: data.token, expiresAt: normalizeExpiry(data.expiresAt) };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Normalize a mint `expiresAt` to ms epoch. The mint contract is ms (matches
+ * `issueGuestToken`), but tolerate a seconds value defensively. A missing or
+ * non-positive value falls back to a short TTL so the next call re-mints
+ * rather than caching a never-expiring token forever.
+ */
+function normalizeExpiry(raw: unknown): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+    return Date.now() + GUEST_TOKEN_REFRESH_SLACK_MS;
+  }
+  // Seconds-epoch timestamps are < 1e12; ms-epoch are ~1.7e12 today.
+  return raw < 1e12 ? raw * 1000 : raw;
+}
+
 function uiSupportsResourceMime(
   clientCapabilities: ClientCapabilities | undefined
 ): boolean {

mcp/src/tools/platformTools.ts

@@ -155,7 +155,10 @@ export async function runPlatformOperation<TInput, TOutput extends object>(
   input: TInput,
   transformPayload?: (payload: TOutput) => object
 ) {
-  const token = agent.bearerToken;
+  // Resolve the bearer: the verified token for an authed session, or a
+  // lazily-minted guest token for an anonymous one. Minting happens here (on
+  // first tool execution), never at connect/list_tools.
+  const token = await agent.getBearerToken();
   if (!token) {
     return toolError("No bearer token on the request.");
   }