@vantageos/mcp-boilerplate 0.1.2 → 0.2.1

package/README.md

@@ -1,93 +1,141 @@
 # @vantageos/mcp-boilerplate
 
-SELLABLE AS: `mcp-boilerplate` — a clonable MCP server starter for the Claude Code marketplace / VantageRegistry catalogue, published as `@vantageos/mcp-boilerplate` on npm.
+SELLABLE AS: `mcp-boilerplate` — a clonable MCP server starter for the Claude Code marketplace / VantageRegistry catalogue and for ChatGPT, published as `@vantageos/mcp-boilerplate` on npm.
 
-A clonable MCP server skeleton: dual-transport bootstrap (stdio + Streamable
-HTTP, stateless) built exclusively on the official
-[`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
-transports. No custom REST routes ever stand in front of a tool call.
+A clonable MCP server skeleton on the official
+[`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+SDK v2: protocol **2026-07-28** with the 2025 handshake still served, stdio and
+stateless Streamable HTTP from one server definition, its **own OAuth 2.1
+authorization server** (a Clerk person picks an organisation), an MCP Apps UI
+and FR/EN messages. No custom REST route ever stands in front of a tool call.
 
-This is a foundation, not a finished product: it ships one trivial example
-tool (`ping`) whose only purpose is to prove the MCP handshake works on both
-transports. Later layers (protocol-kit result types, auth, multi-tenant
-scoping, UI extensions, i18n) build on top of this bootstrap without
-changing the transport wiring.
+It ships three small example tools (`ping`, `list_items`, `render_items_ui`)
+that exercise every layer. Replace them with yours; the wiring stays.
 
 ## Structure
 
 ```
 src/
   mcpServerFactory.ts   # single MCP server definition, shared by both transports
-  stdio.ts              # official SDK StdioServerTransport entrypoint
+  version.ts            # server name + version, derived from package.json
+  stdio.ts              # serveStdio(factory): both protocol eras over stdio
   http.ts               # Node http.Server adapter around the Hono app
-  httpApp.ts            # official SDK WebStandardStreamableHTTPServerTransport (stateless)
-  auth.ts               # OAuth 2.1 resource-server wiring (@vantageos/mcp-auth-kit)
-  config.ts             # env-derived AuthMode + AuthConfig loaders
-  index.ts              # package exports
-tests/
-  helpers/mcpRpc.ts      # JSON-RPC request helpers for the HTTP transport
-  helpers/authFixtures.ts # test-only RS256 JWT signing fixtures
-  httpHandshake.test.ts  # initialize -> tools/list -> tools/call over Streamable HTTP
-  stdioHandshake.test.ts # same handshake over a real spawned stdio child process
-  oauth.test.ts          # both auth tiers: oauth gate + public no-auth tier
-docs/
-  architecture.md        # wire posture: tool-level vs wire-level protocol version
+  httpApp.ts            # createMcpHandler(factory) on /mcp + the OAuth gate
+  auth.ts               # resource-server wiring (@vantageos/cloud-identity)
+  config.ts             # env-derived AuthMode + external-issuer AuthConfig
+  tenancy.ts            # verified JWT -> tenant; rows filtered by stored orgId
+  oauth/                # own authorization server (cloud-identity decides)
+    authorizationServer.ts  settings.ts  clerk.ts  tokenIssuer.ts
+    clientRegistry.ts       codeStore.ts picker.ts
+  ui/                   # MCP Apps widget + ui:// resource
+skills/connect-mcp-server/SKILL.md   # onboarding skill (English)
+scripts/
+  plugin-manifest.source.json  # the ONE source of every packaging manifest
+  sync-plugin-version.mjs      # generates the four manifests (runs in `npm run build`)
+  generate-signing-key.mjs     # prints an RS256 private JWK for MCP_OAUTH_SIGNING_JWK
+tests/  evals/  docs/
 ```
 
 ## Quick start
 
 ```bash
 npm install
-npm run build
+npm run build && npm run build:ui
 
 # stdio (local client config, e.g. Claude Code / Cursor) — never gated,
 # the local process invoking stdio IS the caller.
 npm run start:stdio
 
-# Streamable HTTP (remote, stateless) — OAuth 2.1 gate by default:
-MCP_OAUTH_ISSUER=https://your-tenant.example.com \
-MCP_OAUTH_AUDIENCE=https://your-mcp-server.example.com \
-PORT=8787 npm run start:http
-
-# Streamable HTTP, no-auth "Public MCP" tier (local/self-host, trusted caller):
+# Streamable HTTP, public tier (local/self-host, trusted caller):
 AUTH_MODE=public PORT=8787 npm run start:http
+
+# Streamable HTTP, OAuth tier (default): this server is its own authorization
+# server. See examples/oauth.env.example for every required variable.
+node scripts/generate-signing-key.mjs   # -> MCP_OAUTH_SIGNING_JWK
+PORT=8787 npm run start:http
 ```
 
-## Authentication tiers
+## Protocol and transports
+
+One factory (`createBoilerplateMcpServer`) builds a fresh `McpServer` per
+request (HTTP) or per connection (stdio). The SDK owns the era decision:
 
-Two tiers, per `mcp-standard.md` "Authentication & Authorization":
+- a **2026-07-28** client opens with `server/discover`; `tools/list`,
+  `server/discover` and `resources/*` results carry `resultType`, `ttlMs` and
+  `cacheScope` from the SDK's `cacheHints` (set once in the factory);
+- a **2025-era** client opens with `initialize` and is served through the SDK's
+  stateless legacy leg on HTTP, or a pinned connection on stdio.
+
+The 2025 floor is **2025-06-18**: the SDK's `supportedProtocolVersions` option
+lists only `2025-11-25` and `2025-06-18`, so an older `initialize` is
+counter-offered `2025-11-25`, never served at its own version. The advertised
+server version is read from `package.json`.
+
+## Tool records
+
+Every tool declares `title`, the four annotations as explicit booleans
+(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), a typed
+input schema and a typed output schema (Zod 4), and returns `structuredContent`
+plus a text block with the same JSON. `tests/toolRecordComplete.test.ts` walks
+`tools/list` and fails on any gap. Annotations are untrusted hints for the
+client (mcp-standard C-15); never gate an action on them alone.
+
+## Authentication tiers
 
 | `AUTH_MODE` | Behavior |
 |---|---|
-| `oauth` (default) | OAuth 2.1 resource server (`@vantageos/mcp-auth-kit`): every `/mcp` HTTP call requires a valid RS256 Bearer JWT, audience/issuer-bound. Missing/invalid token -> `401` + `WWW-Authenticate`. RFC 9728 Protected Resource Metadata served at `/.well-known/oauth-protected-resource`. `/health` stays token-free. Requires `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`. |
-| `public` | No gate at all on the HTTP transport — for local/self-host use where the caller is already trusted. Mirrors the stdio transport's trust model (stdio never had a gate). No `.well-known/oauth-protected-resource` document is served in this mode (there is no authorization server to describe). |
-
-The stdio transport (`stdio.ts`) is never gated in either mode — the local
-process invoking it IS the caller, per `mcp-standard.md`'s trust model for
-local/self-host tools.
-
-`buildHttpApp()` called with no arguments defaults to the `public` tier — this
-is what the transport-skeleton tests (`httpHandshake.test.ts`,
-`protocolKitWiring.test.ts`) exercise, so they need no OAuth configuration.
-The production entrypoint (`http.ts`) always resolves `AUTH_MODE` from the
-environment via `config.ts`, defaulting to `oauth` when unset.
-
-## Server-side i18n (FR/EN error messages)
-
-`src/i18n.ts` localizes MCP error/validation messages (auth rejection, tenant
-refusal, tool input-validation) per `mcp-standard.md`'s bilingual mandate
-(§Bilingual): the client sends `X-MCP-Locale: fr` or `X-MCP-Locale: en`
-(default `en` when absent), and `src/httpApp.ts` + `src/mcpServerFactory.ts`
-route the corresponding message through `t(locale, key)`.
-
-The two resource files (`src/locales/{en,fr}.json`) follow the exact
-namespaced-resource convention shipped by `@vantageos/mosaic-i18n@0.1.1`
-(`node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`): a flat
-`<Namespace>.<category>.<key>` -> string object, FR and EN kept key-for-key
-in lockstep. `mosaic-i18n` itself is a React/`react-i18next` package and
-cannot be called directly from a JSON-RPC server, so its runtime API is not
-imported here — its resource-file shape is reused instead, under this
-boilerplate's own `Mcp` namespace.
+| `oauth` (default) | OAuth 2.1. Without `MCP_OAUTH_ISSUER`, this server is both the authorization server and the resource server (below). With `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`, it is a resource server only, for an external issuer. Missing or invalid token -> `401` + `WWW-Authenticate` pointing at the PRM. |
+| `public` | No gate on HTTP — local/self-host, trusted caller. No authorization-server document is served. |
+
+stdio is never gated in either mode.
+
+### Own authorization server (ruling R1)
+
+| Route | Role |
+|---|---|
+| `GET /.well-known/oauth-authorization-server` (+ `openid-configuration`) | RFC 8414 metadata: S256 only, RFC 9207 `iss`, CIMD and DCR advertised |
+| `GET /.well-known/oauth-protected-resource/mcp` | RFC 9728 PRM (`resource` = `<base>/mcp`) via cloud-identity |
+| `GET /.well-known/jwks.json` | public signing keys only |
+| `POST /register` | Dynamic Client Registration fallback (public clients, PKCE) |
+| `GET /authorize`, `GET /authorize/callback`, `POST /authorize/org` | Clerk sign-in, then the person + organisation picker with consent |
+| `POST /token` | `authorization_code` + PKCE S256 -> RS256 JWT bound to the resource, the issuer and the chosen organisation |
+| `GET /userinfo` | OIDC subject (and email when the scope allows) |
+
+Every decision — redirect/PKCE/resource/scope checks, the consent token, code
+binding and redemption, discovery and userinfo shapes — is made by
+`@vantageos/cloud-identity` (`startAuthorize`, `resumeAuthorize`,
+`exchangeAuthorizationCode`, `buildDiscoveryDocument`, `buildUserInfo`). This app
+supplies the environment, the stores, the Clerk calls, the picker page and the
+signature. A client may identify itself by a Client ID Metadata Document URL
+(fetched SSRF-guarded) or register through `/register`.
+
+**Fail-closed**: a missing variable (`PUBLIC_BASE_URL`, `CLERK_DOMAIN`,
+`AUTHORIZE_SIGN_IN_URL`, `AUTHORIZE_CALLBACK_URL`, `AUTHORIZE_STATE_SECRET`,
+`CLERK_SECRET_KEY`, `MCP_OAUTH_SIGNING_JWK`) answers `503` and is named in the
+log (names, never values). There is no auto-approve path.
+
+**Stores**: the authorization-code store and the client registry are interfaces
+with in-memory adapters for tests and single-process development. Use durable
+adapters in production — contract in [`docs/oauth-stores.md`](docs/oauth-stores.md).
+
+**Not included**: refresh tokens (access tokens last one hour), per-organisation
+API keys for non-ChatGPT clients (this code never had that path; it is a gap, not
+a regression), wildcard redirect URIs, and a token revocation list.
+
+### Multi-tenancy
+
+`list_items` filters rows by their stored `orgId` against the caller's verified
+organisation (`isRowInTenant`); a token with no organisation gets an explicit
+tool refusal, never an unscoped view. Resolve the caller's tenant only from the
+verified token, never from a tool argument.
+
+## Server-side i18n (FR/EN)
+
+`src/i18n.ts` localizes MCP error/validation messages and the picker page: the
+client sends `X-MCP-Locale: fr|en` (default `en`); the browser picker follows
+`Accept-Language`. Resource files (`src/locales/{en,fr}.json`) keep the
+`<Namespace>.<category>.<key>` convention of `@vantageos/mosaic-i18n`, FR and EN
+in lockstep.
 
 ## Testing
 
@@ -95,91 +143,80 @@ boilerplate's own `Mcp` namespace.
 npm test
 ```
 
-Runs both transports against the real official-SDK code paths: the HTTP
-suite drives the Hono app in-process; the stdio suite spawns the built
-`dist/stdio.js` binary as a real child process via `StdioClientTransport`.
+Runs both transports through the real SDK code paths: the HTTP suite drives the
+Hono app in-process with the SDK v2 `Client`; the stdio suite spawns the built
+`dist/stdio.js`. `npm run evals` runs the declarative case-set against stdio.
 
 ## Adding a tool
 
-Register it once in `src/mcpServerFactory.ts` — it is then available on
-both transports automatically. There is no separate REST route to add.
+Register it once in `src/mcpServerFactory.ts` with `title`, the four
+annotations, `inputSchema` and `outputSchema`, and return
+`structuredResult(...)`. It is then served on both transports and both
+protocol eras. `tests/toolRecordComplete.test.ts` keeps it honest.
 
 ## Packaging & distribution
 
-This boilerplate is itself a publishable/clonable npm package. Two artifacts
-carry its distribution identity:
-
-- `package.json` — the npm package. `files` ships only the built `dist/` tree
-  (compiled server + `dist/locales/` + `dist/ui-bundle/widget.html`), the
-  `README.md`, the `LICENSE`, the plugin manifest, and the example client
-  config — never `src/`, tests, or tooling. `main`/`types`/`exports` point at
-  `dist/index.js`; the `mcp-boilerplate` bin points at `dist/stdio.js`.
-  `publishConfig.access = public` is required for the `@vantageos` scope.
-- `.claude-plugin/plugin.json` — the Claude Code marketplace / VantageRegistry
-  catalogue manifest, following the fleet MCP-server convention (mirrors
-  `vantage-frameworks-mcp` / `vantage-agent-composer-mcp`): `name`, `version`,
-  bilingual `description` + `description_fr`, `author`, `license`, `homepage`,
-  `category: "mcp-server"`, `bilingual: true`, `keywords`.
+Four manifests are **generated** from `scripts/plugin-manifest.source.json` and
+`package.json` by `scripts/sync-plugin-version.mjs` (part of `npm run build`).
+Never edit them by hand; `tests/pluginManifests.test.ts` fails on drift.
+
+| File | For |
+|---|---|
+| `.claude-plugin/plugin.json` | Claude Code marketplace; non-standard fields (`description_fr`, `category`, `bilingual`) sit under `metadata` |
+| `.mcp.json` | Claude Code: `type: http`, URL only, no secret |
+| `plugin.json` + `mcp.json` | OpenAI Agent Plugins; `streamable-http`, auth under `extensions["com.openai"].auth` (OAuth, CIMD preferred, DCR fallback) |
+
+The server URL is one placeholder in the source file. Set it for a real
+deployment with `MCP_SERVER_URL=https://your-host/mcp node scripts/sync-plugin-version.mjs`
+(both entries change), or leave Claude's `${MCP_BOILERPLATE_URL:-<placeholder>}`
+to be overridden by the installer. The onboarding skill is
+`skills/connect-mcp-server/SKILL.md`, declared for OpenAI as
+`extensions["com.openai"].onboardingSkill`.
 
 ### Scaffold → build → publish
 
 ```bash
-# 1. Scaffold: clone this repo (or the npm tarball) as your server's skeleton.
 git clone https://github.com/elpiarthera/vantage-mcp-boilerplate.git my-mcp
-cd my-mcp && npm install --legacy-peer-deps   # see dev peer-range note above
-
-# 2. Rename: set package.json "name"/"bin" and .claude-plugin/plugin.json
-#    "name" to your server, then add tools in src/mcpServerFactory.ts.
-
-# 3. Build + verify from a clean tree (what CI and prepublishOnly enforce):
-rm -rf dist node_modules/.vite && npm run build && npm test && npm run evals
-
-# 4. Inspect the tarball before publishing — confirm dist/ ships and nothing leaks:
-npm pack --dry-run
-
-# 5. Publish to the two channels:
-npm publish                 # npm registry (prepublishOnly re-runs build+test+evals)
-#   VantageRegistry catalogue: register .claude-plugin/plugin.json via
-#   the fleet create-plugin / generate-marketplace skill (VR upsert).
+cd my-mcp && npm install
+# Rename package.json "name"/"bin" and the names in scripts/plugin-manifest.source.json,
+# then add your tools in src/mcpServerFactory.ts.
+rm -rf dist && npm run build && npm run build:ui && npm test && npm run evals
+npm pack --dry-run          # confirm dist/, manifests and skills/ ship
+npm publish                 # prepublishOnly re-runs build + test + evals
 ```
 
-`prepublishOnly` re-runs `build → build:ui → test → evals` so a broken or
-src-only tarball can never reach npm. The distribution channels are **npm**
-(the runnable package) and the **VantageRegistry / Claude Code marketplace
-catalogue** (discovery, via `plugin.json`).
+Publication is proven at the registry's `dist-tag`, never by the exit code of
+`npm publish`.
 
 ## MCP Apps UI layer
 
-`render_items_ui` renders `EXAMPLE_ITEMS` as an interactive widget via the
-official `@modelcontextprotocol/ext-apps/server` (`registerAppTool` +
-`registerAppResource`), GA `_meta.ui.resourceUri` nested form (stable
-2026-01-26) — never the deprecated flat `_meta["ui/resourceUri"]` key. A
-markdown fallback is always present in `content[0]`, even for clients that
-never negotiate the `io.modelcontextprotocol/ui` extension.
-
-The widget (`src/ui/`) reuses a vendored `MosaicCard` family
-(`src/ui/mosaic-card.tsx` — style-only presentational atoms, no runtime
-dependency) and is bundled to a single self-contained HTML file
-(`vite-plugin-singlefile`, `dist/ui-bundle/widget.html`, ~70 KB gzipped, no
-external runtime fetch). `npm run build:ui` produces this bundle
-independently of `npm run build` (tsc), on a non-colliding output path
-(`dist/ui-bundle/` vs tsc's `dist/ui/`) — the two build steps write to the
-same-looking `dist/ui*` tree but never share a directory, so
-`emptyOutDir` on the vite side can never delete a tsc-compiled server
-module.
-
-**Template hygiene**: the `MosaicCard` atoms are vendored locally rather
-than pulled from `@vantageos/mosaic-blocks`, an internal package with no
-stable (non-alpha) npm release. A fork-template devDependency pinned to a
-moving alpha tag breaks on the next alpha bump; vendoring the four
-presentational primitives the widget actually uses removes that failure
-mode entirely.
-
-**Publish ordering (hard requirement)**: this boilerplate depends on
-`@vantageos/mcp-protocol-kit@^0.2.0`. The `tools/list` wiring uses the kit's
-`buildToolsListResult`, which exists ONLY in kit 0.2.0+. In 0.x semver `^0.2.0`
-does NOT accept 0.1.x, so a fresh `npm install` from the registry resolves the
-kit build the code actually needs. Therefore **kit `@vantageos/mcp-protocol-kit`
-0.2.0 MUST be published to npm BEFORE this boilerplate can be installed or
-published from the registry.** This is a strict ordering, not optional: publish
-the kit first, confirm 0.2.0 is live at the registry, then the boilerplate.
+`render_items_ui` renders `EXAMPLE_ITEMS` as an interactive widget
+(`io.modelcontextprotocol/ui`, spec 2026-01-26).
+
+- The tool links its `ui://` resource through the nested `_meta.ui.resourceUri`
+  with explicit `visibility: ["model", "app"]`. The tool is registered with
+  `server.registerTool`, not ext-apps' `registerAppTool`, because that helper
+  also writes the deprecated flat `_meta["ui/resourceUri"]` key (mcp-app-standard A-6).
+- The resource declares `_meta.ui`: `csp` with `connectDomains`,
+  `resourceDomains`, `frameDomains` and `baseUriDomains` (all empty — the widget
+  makes no network request, loads no third-party asset and embeds no frame),
+  `prefersBorder`, and `domain` only when `MCP_UI_DOMAIN` is set (the format is
+  host-dependent). Its mime type is `text/html;profile=mcp-app`.
+- **ChatGPT keys are additive**: `openai/outputTemplate` (same URI) and the
+  `openai/toolInvocation/invoking|invoked` strings. Nothing reads them; the
+  server works with every `openai/*` key absent. `openai/ui` entrypoints are
+  not emitted — they are optional; add them to the tool `_meta` in
+  `src/ui/uiResource.ts` if your ChatGPT app needs them.
+- A markdown fallback is always in the call result, for clients that never
+  negotiate the extension.
+
+The widget (`src/ui/`) reuses a vendored `MosaicCard` family and is bundled to
+one self-contained HTML file (`vite-plugin-singlefile`,
+`dist/ui-bundle/widget.html`) by `npm run build:ui`, on a path that never
+collides with tsc's `dist/ui/`.
+
+**Identity layer**: `@vantageos/cloud-identity` (^0.15.0) is the only identity
+package. Its resource-server entry point (`verifyMcpAccessToken`,
+`buildProtectedResourceMetadata`) verifies the Bearer token on `/mcp`; `jose` is
+kept only to mint the authorization server's access tokens. An unreachable key set
+answers 503, never 401.

package/dist/auth.d.ts

@@ -1,11 +1,12 @@
 /**
  * OAuth 2.1 resource-server wiring for this MCP server's HTTP transport.
  *
- * Reuses @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` facade
- * unmodified — this module never hand-rolls JWT verification. It only
- * supplies configuration (issuer, audience, JWKS resolver, resource
- * metadata URL) and adapts the facade's result to a plain
- * accept/reject decision for the HTTP transport.
+ * Built on @vantageos/cloud-identity's resource-server entry point
+ * (`verifyMcpAccessToken`, `buildProtectedResourceMetadata`) — the ONLY identity layer of this
+ * boilerplate. This module never hand-rolls JWT verification. It only supplies configuration
+ * (issuer, audience, key set, resource metadata URL) and returns the verifier's result to the
+ * HTTP transport: accepted (with the verified session), refused 401 (with the RFC 6750
+ * challenge), or 503 when the key set is unreachable (an outage, never a bad credential).
  *
  * This is the "OAuth 2.1" tier of the two auth tiers this boilerplate
  * supports (see config.ts `AuthMode`). The other tier — "public" — never
@@ -13,15 +14,24 @@
  * stdio transport (stdio.ts) never had a gate to begin with (local process
  * trust model, per mcp-standard.md).
  */
-import { type McpResourceServerResult } from "@vantageos/mcp-auth-kit";
-import type { JWTVerifyGetKey } from "jose";
+import { type ClerkJwks, type VerifyMcpAccessTokenResult } from "@vantageos/cloud-identity";
 export interface AuthConfig {
     realm: string;
     resourceMetadataUrl: string;
-    jwks: JWTVerifyGetKey;
+    /**
+     * The protected-resource identifier published in the PRM (RFC 9728). Defaults to the origin
+     * of `resourceMetadataUrl` (the pre-0.2 behaviour, kept for external-issuer deployments);
+     * the own-authorization-server tier sets it to `<base>/mcp`.
+     */
+    resource?: string;
+    /**
+     * The signing keys: a `{ keys }` JWK set, or a function returning one. The consumer owns
+     * fetching and caching (config.ts `createCachedJwksFetcher` for an external issuer).
+     */
+    jwks: ClerkJwks | (() => Promise<ClerkJwks>);
     issuer: string;
     audience: string;
     authorizationServers: string[];
 }
-export declare function authenticateRequest(authHeader: string | undefined, config: AuthConfig): Promise<McpResourceServerResult>;
-export declare function protectedResourceMetadataDocument(config: AuthConfig): import("@vantageos/mcp-auth-kit").ProtectedResourceMetadataDocument;
+export declare function authenticateRequest(authHeader: string | undefined, config: AuthConfig): Promise<VerifyMcpAccessTokenResult>;
+export declare function protectedResourceMetadataDocument(config: AuthConfig): import("@vantageos/cloud-identity").ProtectedResourceMetadata;

package/dist/auth.js

@@ -1,11 +1,12 @@
 /**
  * OAuth 2.1 resource-server wiring for this MCP server's HTTP transport.
  *
- * Reuses @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` facade
- * unmodified — this module never hand-rolls JWT verification. It only
- * supplies configuration (issuer, audience, JWKS resolver, resource
- * metadata URL) and adapts the facade's result to a plain
- * accept/reject decision for the HTTP transport.
+ * Built on @vantageos/cloud-identity's resource-server entry point
+ * (`verifyMcpAccessToken`, `buildProtectedResourceMetadata`) — the ONLY identity layer of this
+ * boilerplate. This module never hand-rolls JWT verification. It only supplies configuration
+ * (issuer, audience, key set, resource metadata URL) and returns the verifier's result to the
+ * HTTP transport: accepted (with the verified session), refused 401 (with the RFC 6750
+ * challenge), or 503 when the key set is unreachable (an outage, never a bad credential).
  *
  * This is the "OAuth 2.1" tier of the two auth tiers this boilerplate
  * supports (see config.ts `AuthMode`). The other tier — "public" — never
@@ -13,9 +14,9 @@
  * stdio transport (stdio.ts) never had a gate to begin with (local process
  * trust model, per mcp-standard.md).
  */
-import { buildProtectedResourceMetadata, verifyMcpBearerRequest, } from "@vantageos/mcp-auth-kit";
+import { buildProtectedResourceMetadata, verifyMcpAccessToken, } from "@vantageos/cloud-identity";
 export async function authenticateRequest(authHeader, config) {
-    return verifyMcpBearerRequest(authHeader, {
+    return verifyMcpAccessToken(authHeader, {
         realm: config.realm,
         resourceMetadataUrl: config.resourceMetadataUrl,
         jwks: config.jwks,
@@ -25,7 +26,7 @@ export async function authenticateRequest(authHeader, config) {
 }
 export function protectedResourceMetadataDocument(config) {
     return buildProtectedResourceMetadata({
-        resource: config.resourceMetadataUrl.replace(/\/\.well-known\/.*/, ""),
+        resource: config.resource ?? config.resourceMetadataUrl.replace(/\/\.well-known\/.*/, ""),
         authorizationServers: config.authorizationServers,
     });
 }

package/dist/config.d.ts

@@ -13,9 +13,16 @@
  * URL, issuer, audience) comes from the environment, never a literal in
  * code.
  */
-import { type JWTVerifyGetKey, createLocalJWKSet } from "jose";
+import type { ClerkJwks } from "@vantageos/cloud-identity";
 import type { AuthConfig } from "./auth.js";
 export type AuthMode = "oauth" | "public";
 export declare function loadAuthMode(env?: NodeJS.ProcessEnv): AuthMode;
-export declare function loadAuthConfig(env?: NodeJS.ProcessEnv, jwksOverride?: JWTVerifyGetKey): AuthConfig;
-export { createLocalJWKSet };
+export declare function loadAuthConfig(env?: NodeJS.ProcessEnv, jwksOverride?: AuthConfig["jwks"]): AuthConfig;
+/**
+ * Fetch-and-cache for an external issuer's JWKS. cloud-identity's resource server takes the key
+ * set (or a function returning it) and owns no network I/O, so this boilerplate owns it: one
+ * GET of the JWKS document, cached for ten minutes. A failed fetch throws — the verifier turns
+ * that into a 503 (`jwks-unavailable`), never a 401 — unless a previously fetched set is still
+ * held, which is served rather than failing every request during a brief issuer blip.
+ */
+export declare function createCachedJwksFetcher(url: string, fetchImpl?: typeof fetch, nowMs?: () => number): () => Promise<ClerkJwks>;

package/dist/config.js

@@ -13,7 +13,6 @@
  * URL, issuer, audience) comes from the environment, never a literal in
  * code.
  */
-import { createLocalJWKSet, createRemoteJWKSet } from "jose";
 export function loadAuthMode(env = process.env) {
     const raw = (env.AUTH_MODE ?? "oauth").toLowerCase();
     if (raw !== "oauth" && raw !== "public") {
@@ -30,7 +29,7 @@ export function loadAuthConfig(env = process.env, jwksOverride) {
             "oauth mode (OAuth 2.1 resource-server requirement — mcp-standard.md Critical Rule #14). " +
             "Set AUTH_MODE=public instead to run the no-auth local/self-host tier.");
     }
-    const jwks = jwksOverride ?? createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`));
+    const jwks = jwksOverride ?? createCachedJwksFetcher(`${issuer}/.well-known/jwks.json`);
     return {
         realm: "mcp",
         resourceMetadataUrl: `${publicBaseUrl}/.well-known/oauth-protected-resource`,
@@ -40,4 +39,33 @@ export function loadAuthConfig(env = process.env, jwksOverride) {
         authorizationServers: [issuer],
     };
 }
-export { createLocalJWKSet };
+const JWKS_TTL_MS = 10 * 60 * 1000;
+/**
+ * Fetch-and-cache for an external issuer's JWKS. cloud-identity's resource server takes the key
+ * set (or a function returning it) and owns no network I/O, so this boilerplate owns it: one
+ * GET of the JWKS document, cached for ten minutes. A failed fetch throws — the verifier turns
+ * that into a 503 (`jwks-unavailable`), never a 401 — unless a previously fetched set is still
+ * held, which is served rather than failing every request during a brief issuer blip.
+ */
+export function createCachedJwksFetcher(url, fetchImpl = fetch, nowMs = Date.now) {
+    let cached;
+    return async () => {
+        if (cached && nowMs() - cached.fetchedAt < JWKS_TTL_MS)
+            return cached.jwks;
+        try {
+            const res = await fetchImpl(url);
+            if (!res.ok)
+                throw new Error(`JWKS fetch ${url} answered ${res.status}`);
+            const body = (await res.json());
+            if (!body || !Array.isArray(body.keys))
+                throw new Error(`JWKS document at ${url} has no keys`);
+            cached = { jwks: body, fetchedAt: nowMs() };
+            return body;
+        }
+        catch (err) {
+            if (cached)
+                return cached.jwks;
+            throw err;
+        }
+    };
+}

package/dist/exampleItems.d.ts

@@ -1,12 +1,13 @@
 /**
- * Seed data for the `list_items` multi-tenant example tool. `createdBy` and
- * `namespace` follow the tenant-id convention documented in tenancy.ts
- * (`scopeForTenant`) — each row is owned by, and namespaced under, exactly
- * one tenant.
+ * Seed data for the `list_items` multi-tenant example tool. Each row is stamped with the
+ * stored `orgId` of the organisation that owns it — the row is selected by comparing that
+ * stored id with the caller's verified organisation (tenancy.ts `isRowInTenant`), never by
+ * a creator name. `createdBy` / `namespace` stay as display fields only.
  */
 export interface ExampleItem {
     id: string;
     name: string;
+    orgId: string;
     createdBy: string;
     namespace: string;
 }

package/dist/exampleItems.js

@@ -2,18 +2,21 @@ export const EXAMPLE_ITEMS = [
     {
         id: "item-1",
         name: "Tenant A widget",
+        orgId: "org_a",
         createdBy: "org_a",
         namespace: "org_a",
     },
     {
         id: "item-2",
         name: "Tenant A gadget",
+        orgId: "org_a",
         createdBy: "org_a",
         namespace: "org_a",
     },
     {
         id: "item-3",
         name: "Tenant B widget",
+        orgId: "org_b",
         createdBy: "org_b",
         namespace: "org_b",
     },

package/dist/http.js

@@ -1,7 +1,17 @@
 import { loadAuthConfig, loadAuthMode } from "./config.js";
 import { buildHttpApp } from "./httpApp.js";
 const authMode = loadAuthMode();
-const app = buildHttpApp(authMode === "oauth" ? { authMode, auth: loadAuthConfig() } : { authMode });
+const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
+// OAuth tier: MCP_OAUTH_ISSUER + MCP_OAUTH_AUDIENCE select an EXTERNAL issuer (resource server
+// only); otherwise this server is its own authorization server (ruling R1) and reads its
+// settings from the environment per request — a missing value answers 503, see
+// src/oauth/settings.ts.
+const externalIssuer = Boolean(process.env.MCP_OAUTH_ISSUER && process.env.MCP_OAUTH_AUDIENCE);
+const app = buildHttpApp(authMode === "oauth"
+    ? externalIssuer
+        ? { authMode, auth: loadAuthConfig(), uiDomain }
+        : { authMode, authorizationServer: {}, uiDomain }
+    : { authMode, uiDomain });
 const port = Number(process.env.PORT ?? 8787);
 // Hono's fetch handler adapted onto Node's http server (no extra framework
 // dependency beyond hono + node:http).