@ultimat3/mcp 22.5.1 → 22.6.1

package/CLAUDE.md

@@ -22,6 +22,7 @@ import. The CLI wires it.
 | `dev-server.ts` | the 13 dev tools; depends only on an injected `DevHost` |
 | `dev-host.ts` | wires `describe*` from entity/action/query/jobs into a `DevHost` |
 | `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor, and the per-caller rate limit it enforces itself |
+| `oauth-metadata.ts` | RFC 9728 protected-resource metadata + the 401 `resource_metadata` challenge (`defineAppMcp({ oauth })`); the authorization server is the app's |
 | `transport-stdio.ts` | NDJSON on stdin/stdout for `x mcp serve` |
 | `app-tools.ts` | `defineAppMcp` — a generated app's own MCP surface, one call |
 | `app-tool.ts` | the authored `tools: { name: {...} }` record → `ProjectablePrimitive` |

package/README.md

@@ -253,6 +253,19 @@ did not.
 | the body cap | `mcpHttpRoute({ bodyLimitBytes })` · `defineAppMcp({ bodyLimitBytes })` | `DEFAULT_MCP_BODY_LIMIT_BYTES`, 1 MiB |
 | the numbers | `mcpHttpRoute({ rateLimits })` · `defineAppMcp({ rateLimits })` | `MCP_RATE_LIMITS` |
 | where they are counted | `mcpHttpRoute({ rateLimitStore })` · `defineAppMcp({ rateLimitStore })` | a per-**process** memory store — N replicas behind one URL each enforce the full allowance, so a fleet passes `postgresRateLimitStore({ executor })` |
+| OAuth discovery | `mcpHttpRoute({ oauth })` · `defineAppMcp({ oauth })` | absent: the 401 is `Bearer realm="ultimate-mcp"` |
+
+### OAuth discovery (RFC 9728)
+
+`defineAppMcp({ oauth: { authorizationServers: ['https://www.example.com'] } })` (`As of 22.6.0`;
+MCP authorization spec 2025-06-18, unchanged in 2025-11-25): every 401 carries
+`WWW-Authenticate: Bearer realm="ultimate-mcp", resource_metadata="<origin>/.well-known/oauth-protected-resource<path>"`
+(`error="invalid_token"` when a token was sent), and `route.protectedResource` carries the document
+and the two paths it is served at — path-inserted per RFC 9728 §3.1 and the root — which
+`@ultimat3/cli` mounts as public `GET`s beside `POST /mcp`. `resource` defaults to the request's
+PUBLIC origin (`handle(request, { origin })`, which the boot fills from `ctx.https`) + the mount
+path; `scopes_supported` to the `scopes` map's keys. Issuers must be https (http on loopback):
+`X_MCP_OAUTH_INVALID`. The authorization server is the app's own routes.
 
 ## Resources
 
@@ -274,6 +287,24 @@ implements the emitted subset (objects, arrays, enums, `required`, `additionalPr
 bounds, `default`) and applies declared defaults. Actions still re-parse authoritatively
 inside their own handler.
 
+## Idempotency over MCP
+
+An `idempotent: true` action's tool carries one reserved, optional argument,
+`MCP_IDEMPOTENCY_KEY_ARG` (`'idempotencyKey'`, string, 1–255), advertised in `tools/list` and held
+to that schema here. `tools/call` takes it out of the arguments and hands it to `invoke` as the
+idempotency key — what the `Idempotency-Key` header is over HTTP, filed under action, caller and
+key — so an agent retrying a timed-out call with the same key gets the first result back:
+
+```json
+{ "method": "tools/call", "params": { "name": "sendNotification",
+  "arguments": { "caseId": "c1", "idempotencyKey": "7f0c…" } } }
+```
+
+The action's own input never sees the key. A non-idempotent tool does not advertise it and refuses
+it (`X_MCP_ARGS_INVALID`). An argument, not `params._meta`: `_meta` is for host metadata and a
+model-driven client cannot set it. An idempotent action whose input already names `idempotencyKey`
+is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
+
 ## Errors
 
 | Code | Meaning |
@@ -283,6 +314,7 @@ inside their own handler.
 | `X_MCP_SCOPE_UNKNOWN` | `defineAppMcp`'s `scopes:` names a tool this server does not project |
 | `X_MCP_SCOPE_CONFLICT` | two scopes in `defineAppMcp`'s `scopes:` claim one tool |
 | `X_MCP_ARGS_INVALID` | arguments failed the declared schema |
+| `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | an idempotent action's input declares `idempotencyKey`, the reserved retry-key argument |
 | `X_MCP_PROTOCOL` | malformed envelope, unknown method, bad auth header |
 | `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
 | `X_MCP_NOT_BRANCH_DB` | `db.migrate` aimed at a production or otherwise non-branch database |
@@ -302,6 +334,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpAppUnmountedError` | `X_MCP_APP_UNMOUNTED` | `src/errors.ts` |
 | `McpArgsInvalidError` | `X_MCP_ARGS_INVALID` | `src/errors.ts` |
 | `McpBodyTooLargeError` | `X_MCP_BODY_TOO_LARGE` | `src/errors.ts` |
+| `McpIdempotencyKeyShadowedError` | `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | `src/errors.ts` |
 | `McpGroupConflictError` | `X_MCP_GROUP_CONFLICT` | `src/meta-errors.ts` |
 | `McpGroupUnknownError` | `X_MCP_GROUP_UNKNOWN` | `src/meta-errors.ts` |
 | `McpListParamsInvalidError` | `X_MCP_LIST_PARAMS_INVALID` | `src/meta-errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.5.1",
+  "version": "22.6.1",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.5.1",
-    "@ultimat3/core": "22.5.1",
-    "@ultimat3/entity": "22.5.1",
-    "@ultimat3/http": "22.5.1",
-    "@ultimat3/jobs": "22.5.1",
-    "@ultimat3/policy": "22.5.1",
-    "@ultimat3/query": "22.5.1",
-    "@ultimat3/schema": "22.5.1"
+    "@ultimat3/action": "22.6.1",
+    "@ultimat3/core": "22.6.1",
+    "@ultimat3/entity": "22.6.1",
+    "@ultimat3/http": "22.6.1",
+    "@ultimat3/jobs": "22.6.1",
+    "@ultimat3/policy": "22.6.1",
+    "@ultimat3/query": "22.6.1",
+    "@ultimat3/schema": "22.6.1"
   }
 }

package/src/app-tools.ts

@@ -16,6 +16,7 @@ import { McpToolDuplicateError } from './errors';
 import { exposedPrimitives } from './exposed';
 import { toolsFrom, toolsListed } from './from-action';
 import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
+import type { McpOAuth } from './oauth-metadata';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
 import type { AnyMcpTool, McpVerbClass } from './registry';
@@ -118,6 +119,17 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    * `postgresRateLimitStore({ executor })` the web role takes.
    */
   readonly rateLimitStore?: RateLimitStore | undefined;
+  /**
+   * OAuth discovery for remote MCP clients (the MCP authorization spec, RFC 9728): the route's 401
+   * says `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp"`,
+   * and the boot serves that document (and the root one) naming `authorizationServers`. The
+   * authorization server — consent, `/oauth/token` — is the app's own routes.
+   *
+   * ```ts
+   * oauth: { authorizationServers: ['https://www.example.com'], resourceName: 'Example' },
+   * ```
+   */
+  readonly oauth?: McpOAuth | undefined;
 }
 
 export interface AppMcp {
@@ -201,6 +213,9 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
           ...(input.bodyLimitBytes !== undefined ? { bodyLimitBytes: input.bodyLimitBytes } : {}),
           ...(input.rateLimits !== undefined ? { rateLimits: input.rateLimits } : {}),
           ...(input.rateLimitStore !== undefined ? { rateLimitStore: input.rateLimitStore } : {}),
+          ...(input.oauth === undefined
+            ? {}
+            : { oauth: input.oauth, scopes: Object.keys(input.scopes ?? {}) }),
         });
 
   return { server, tools: projected, route };

package/src/errors.ts

@@ -23,6 +23,8 @@ export const MCP_ERROR_CODES = [
   'X_MCP_GROUP_CONFLICT',
   'X_MCP_SURFACE_INVALID',
   'X_MCP_LIST_PARAMS_INVALID',
+  'X_MCP_OAUTH_INVALID',
+  'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -47,6 +49,9 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_GROUP_CONFLICT: 'two resource groups claim one MCP tool',
   X_MCP_SURFACE_INVALID: 'the MCP meta surface is declared inconsistently',
   X_MCP_LIST_PARAMS_INVALID: "a tool's listParams names a key its own input does not accept",
+  X_MCP_OAUTH_INVALID: 'the MCP oauth block cannot be published as protected-resource metadata',
+  X_MCP_IDEMPOTENCY_KEY_SHADOWED:
+    "an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -417,3 +422,30 @@ export class McpRateLimitedError extends UltimateError {
     });
   }
 }
+
+/** `defineAppMcp({ oauth })` refused at boot — see `oauth-metadata.ts`. */
+export class McpOAuthInvalidError extends UltimateError {
+  constructor(reason: string) {
+    super({
+      code: 'X_MCP_OAUTH_INVALID',
+      cause: `defineAppMcp({ oauth }) cannot be published as protected-resource metadata: ${reason}`,
+      fix: "defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL; resource and resourceDocumentation, when set, absolute URLs with no fragment",
+    });
+  }
+}
+
+/**
+ * An idempotent action's tool carries the reserved `idempotencyKey` argument, and this action's
+ * own input already names a field that. One argument cannot be both the input a handler reads and
+ * the key a retry replays under, so the projection refuses at boot instead of guessing which.
+ */
+export class McpIdempotencyKeyShadowedError extends UltimateError {
+  constructor(input: { readonly name: string; readonly argument: string }) {
+    super({
+      code: 'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
+      cause: `${input.name} is idempotent and its input declares "${input.argument}", the MCP argument reserved for the idempotency key`,
+      fix: `rename ${input.name}'s "${input.argument}" input field — MCP clients send the Idempotency-Key as the reserved "${input.argument}" argument, and the action receives the rest`,
+      meta: { action: input.name, argument: input.argument },
+    });
+  }
+}

package/src/idempotency-arg.ts

@@ -0,0 +1,73 @@
+// The MCP half of `idempotent: true`: the Idempotency-Key an HTTP caller sends as a header, sent
+// by an MCP caller as one reserved, optional tool ARGUMENT. An argument and not `params._meta`:
+// `_meta` is protocol metadata a host fills (a progress token), and no model-driven client lets the
+// model set it — the retry that needs a key is the agent's own, so the key goes where the agent
+// writes. It is advertised in `tools/list`, enforced by `validate-args.ts` like every other field,
+// and taken back out before `invoke`, so the action's own input parse never sees it.
+
+import { MAX_IDEMPOTENCY_KEY_LENGTH } from '@ultimat3/action';
+import { McpIdempotencyKeyShadowedError } from './errors';
+import type { JsonSchema } from './wire';
+
+/** The reserved argument name on every idempotent action's tool. */
+export const MCP_IDEMPOTENCY_KEY_ARG = 'idempotencyKey';
+
+/**
+ * Contract text, not UI text — it is what `tools/list` publishes, the same bytes for every caller,
+ * like an action's `mcp.description`.
+ */
+const DESCRIPTION =
+  'Idempotency key. Retrying this call with the same key and the same arguments returns the ' +
+  'first result instead of running it again; the same key with different arguments is refused. ' +
+  'Any unique string, e.g. a UUID — reuse it only to retry.';
+
+const KEY_SCHEMA: JsonSchema = {
+  type: 'string',
+  description: DESCRIPTION,
+  minLength: 1,
+  maxLength: MAX_IDEMPOTENCY_KEY_LENGTH,
+};
+
+/**
+ * `schema` with the optional key argument. An input that is not an object has no argument to
+ * add, and is left alone; one that already names the argument is refused, never merged.
+ */
+export function withIdempotencyKeyArg(name: string, schema: JsonSchema): JsonSchema {
+  if (schema.type !== 'object') return schema;
+  const properties = schema.properties ?? {};
+  if (Object.hasOwn(properties, MCP_IDEMPOTENCY_KEY_ARG)) {
+    throw new McpIdempotencyKeyShadowedError({ name, argument: MCP_IDEMPOTENCY_KEY_ARG });
+  }
+  return { ...schema, properties: { ...properties, [MCP_IDEMPOTENCY_KEY_ARG]: KEY_SCHEMA } };
+}
+
+/**
+ * The call's arguments split into the action's input and the key. Absent, empty-handed or not an
+ * object: the input as given and no key — `invoke` then runs the action un-keyed, as HTTP does
+ * without the header.
+ */
+export function takeIdempotencyKeyArg(args: unknown): {
+  readonly input: unknown;
+  readonly idempotencyKey: string | null;
+} {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { input: args, idempotencyKey: null };
+  }
+  if (!Object.hasOwn(args, MCP_IDEMPOTENCY_KEY_ARG)) return { input: args, idempotencyKey: null };
+  const input: Record<string, unknown> = {};
+  let key: unknown;
+  for (const [field, value] of Object.entries(args)) {
+    if (field === MCP_IDEMPOTENCY_KEY_ARG) key = value;
+    // defineProperty, never `input[field] =`: a `__proto__` field would re-prototype the copy.
+    else
+      Object.defineProperty(input, field, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+  }
+  // `validate-args.ts` already held the value to the advertised string schema, so a non-string can
+  // only come from a caller that skipped it — and a value that is not a string is not a key.
+  return { input, idempotencyKey: typeof key === 'string' ? key : null };
+}

package/src/index.ts

@@ -63,7 +63,9 @@ export {
   McpAppUnmountedError,
   McpArgsInvalidError,
   McpBodyTooLargeError,
+  McpIdempotencyKeyShadowedError,
   McpNotBranchDbError,
+  McpOAuthInvalidError,
   McpProtocolError,
   McpQueryRejectedError,
   McpRateLimitedError,
@@ -85,6 +87,7 @@ export {
   toolsFrom,
   toolsListed,
 } from './from-action';
+export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
 export { toWireSchema } from './input-schema';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
@@ -111,6 +114,13 @@ export {
   META_TOOL_NAMES,
   oneLineParams,
 } from './meta-surface';
+export type { McpOAuth } from './oauth-metadata';
+export {
+  metadataPaths,
+  metadataUrlFor,
+  PROTECTED_RESOURCE_WELL_KNOWN,
+  protectedResourceMetadata,
+} from './oauth-metadata';
 export type { ListedPrimitive } from './projectable';
 export { asProjectable } from './projectable';
 export type { QueryLimits, QueryResult, QueryRows } from './query-limits';
@@ -156,6 +166,8 @@ export type { CreateMcpServerInput, McpWire } from './server';
 export { createMcpServer, McpServer } from './server';
 export type {
   McpHttpTransportInput,
+  McpProtectedResource,
+  McpRequestOrigin,
   McpRouteDescriptor,
   ResolvedToken,
 } from './transport-http';

package/src/oauth-metadata.ts

@@ -0,0 +1,114 @@
+// OAuth 2.0 Protected Resource Metadata (RFC 9728) for the MCP endpoint — the framework half of
+// the MCP authorization spec (2025-06-18, unchanged in 2025-11-25): a 401 names where the metadata
+// lives (`WWW-Authenticate: Bearer resource_metadata="…"`), and the metadata names the
+// authorization server(s) a client goes to for a token. The authorization server itself is the
+// APP's — its consent page, its token endpoint, its revocation list — never this package's.
+
+import { McpOAuthInvalidError } from './errors';
+
+/** The well-known suffix RFC 9728 §3 defines. */
+export const PROTECTED_RESOURCE_WELL_KNOWN = '/.well-known/oauth-protected-resource';
+
+export interface McpOAuth {
+  /**
+   * Issuer identifiers of the authorization servers that mint tokens this endpoint accepts
+   * (`authorization_servers`). At least one; an absolute https URL, or http on localhost.
+   */
+  readonly authorizationServers: readonly string[];
+  /**
+   * The canonical URL of this MCP endpoint (RFC 8707 `resource`), e.g.
+   * `https://www.example.com/mcp`. Omitted, it is the request's own public origin + the mount
+   * path — right for one image deployed behind many hosts.
+   */
+  readonly resource?: string;
+  /** `scopes_supported`. Omitted, the keys of `defineAppMcp({ scopes })`. */
+  readonly scopesSupported?: readonly string[];
+  /** `resource_name` — shown by a client's consent screen. */
+  readonly resourceName?: string;
+  /** `resource_documentation` — an absolute URL. */
+  readonly resourceDocumentation?: string;
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/** https anywhere, http only on loopback (RFC 9728 §3.3, OAuth 2.1 §1.5), and never a fragment. */
+function isIssuerUrl(value: string): boolean {
+  const url = URL.parse(value);
+  if (url === null || url.hash !== '') return false;
+  return url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname));
+}
+
+/** At `defineAppMcp`, never on a request. */
+export function assertMcpOAuth(oauth: McpOAuth): void {
+  if (oauth.authorizationServers.length === 0) {
+    throw new McpOAuthInvalidError('authorizationServers is empty');
+  }
+  for (const issuer of oauth.authorizationServers) {
+    if (!isIssuerUrl(issuer)) {
+      throw new McpOAuthInvalidError(
+        `${JSON.stringify(issuer)} is not an absolute https issuer URL`,
+      );
+    }
+  }
+  for (const key of ['resource', 'resourceDocumentation'] as const) {
+    const value = oauth[key];
+    if (value !== undefined && !isIssuerUrl(value)) {
+      throw new McpOAuthInvalidError(
+        `${key} ${JSON.stringify(value)} is not an absolute https URL`,
+      );
+    }
+  }
+}
+
+/** The resource this request addresses: the declared one, else `<origin><path>`. */
+export function resourceUrl(oauth: McpOAuth, origin: string, path: string): string {
+  return oauth.resource ?? `${origin.replace(/\/+$/, '')}${path}`;
+}
+
+/**
+ * RFC 9728 §3.1: the well-known suffix INSERTED between the host and the resource's path —
+ * `https://x.test/mcp` → `https://x.test/.well-known/oauth-protected-resource/mcp`.
+ */
+export function metadataUrlFor(resource: string): string {
+  const url = new URL(resource);
+  const path = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+  return `${url.origin}${PROTECTED_RESOURCE_WELL_KNOWN}${path}`;
+}
+
+/** The two paths a host serves the document at: path-inserted (RFC 9728), and the root. */
+export function metadataPaths(mountPath: string): readonly string[] {
+  const inserted = `${PROTECTED_RESOURCE_WELL_KNOWN}${mountPath === '/' ? '' : mountPath}`;
+  return inserted === PROTECTED_RESOURCE_WELL_KNOWN
+    ? [PROTECTED_RESOURCE_WELL_KNOWN]
+    : [inserted, PROTECTED_RESOURCE_WELL_KNOWN];
+}
+
+/** The metadata document for `resource`. Keys in RFC 9728 §2's names. */
+export function protectedResourceMetadata(
+  oauth: McpOAuth,
+  resource: string,
+  scopes: readonly string[],
+): Record<string, unknown> {
+  const supported = oauth.scopesSupported ?? scopes;
+  return {
+    resource,
+    authorization_servers: [...oauth.authorizationServers],
+    bearer_methods_supported: ['header'],
+    ...(supported.length === 0 ? {} : { scopes_supported: [...supported].sort() }),
+    ...(oauth.resourceName === undefined ? {} : { resource_name: oauth.resourceName }),
+    ...(oauth.resourceDocumentation === undefined
+      ? {}
+      : { resource_documentation: oauth.resourceDocumentation }),
+  };
+}
+
+/**
+ * The challenge a 401 carries. `error="invalid_token"` only when a token WAS sent (RFC 6750
+ * §3.1: a request with no credential gets no error code).
+ */
+export function bearerChallenge(metadataUrl: string | undefined, tokenSent: boolean): string {
+  const params = ['realm="ultimate-mcp"'];
+  if (tokenSent) params.push('error="invalid_token"');
+  if (metadataUrl !== undefined) params.push(`resource_metadata="${metadataUrl}"`);
+  return `Bearer ${params.join(', ')}`;
+}

package/src/projectable.ts

@@ -10,6 +10,7 @@ import type { AnyQuery } from '@ultimat3/query';
 import { isQuery, queryName, sourceFor } from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
+import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
 import { toWireSchema } from './input-schema';
 import type { McpListParams } from './list-params';
 
@@ -40,16 +41,26 @@ export function asProjectable(listed: ListedPrimitive): ProjectablePrimitive {
 
 export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
+  // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than projecting a tool called
+  // `''`: a nameless tool is unaddressable by the scope map, by `tools/call`, and by the author.
+  const name = actionName(target);
+  const wire = toWireSchema(target.input);
+  // `idempotent: true` is honoured on this surface exactly as over HTTP: the caller's key reaches
+  // `invoke`, which files it under the action, the caller and the key (`idempotencyKeyFor`).
+  const keyed = target.describe().idempotent;
   return {
-    // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than projecting a tool called
-    // `''`: a nameless tool is unaddressable by the scope map, by `tools/call`, and by the author.
-    name: actionName(target),
+    name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
-    inputJsonSchema: toWireSchema(target.input),
+    inputJsonSchema: keyed ? withIdempotencyKeyArg(name, wire) : wire,
     mutates: true,
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
-    run: ({ input, actor }) => invoke(target, input, { surface: 'mcp', actor }),
+    run: keyed
+      ? ({ input: args, actor }) => {
+          const { input, idempotencyKey } = takeIdempotencyKeyArg(args);
+          return invoke(target, input, { surface: 'mcp', actor, idempotencyKey });
+        }
+      : ({ input, actor }) => invoke(target, input, { surface: 'mcp', actor }),
   };
 }
 

package/src/transport-http.ts

@@ -24,6 +24,15 @@ import { finiteCount, readWithinLimit, systemClock } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
 import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
 import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
+import type { McpOAuth } from './oauth-metadata';
+import {
+  assertMcpOAuth,
+  bearerChallenge,
+  metadataPaths,
+  metadataUrlFor,
+  protectedResourceMetadata,
+  resourceUrl,
+} from './oauth-metadata';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
 import type { JsonRpcResponse } from './wire';
@@ -75,6 +84,28 @@ export interface McpHttpTransportInput {
   readonly rateLimitStore?: RateLimitStore | undefined;
   /** The one clock the buckets refill on. Defaulted, never read inline, so a test can freeze it. */
   readonly clock?: Clock | undefined;
+  /**
+   * Publish RFC 9728 protected-resource metadata and name it in every 401's `WWW-Authenticate` —
+   * the discovery an OAuth-capable MCP client (a remote connector) starts from. Absent, the 401
+   * says `Bearer realm="ultimate-mcp"` as it always did.
+   */
+  readonly oauth?: McpOAuth | undefined;
+  /** `scopes_supported` when `oauth.scopesSupported` is not stated: the app's scope names. */
+  readonly scopes?: readonly string[] | undefined;
+}
+
+/** How the host saw the request — what a bare `Request` behind a TLS-terminating proxy cannot say. */
+export interface McpRequestOrigin {
+  /** The PUBLIC origin, `https://www.example.com`. Defaults to the request URL's own. */
+  readonly origin?: string | undefined;
+}
+
+/** The metadata half of an `oauth` route: where to serve it and what to answer. */
+export interface McpProtectedResource {
+  /** `/.well-known/oauth-protected-resource/mcp` and the root one. `GET`, public. */
+  readonly paths: readonly string[];
+  /** The document, for the public origin the request arrived on. */
+  document(origin: string): Record<string, unknown>;
 }
 
 export interface McpRouteDescriptor {
@@ -84,7 +115,9 @@ export interface McpRouteDescriptor {
   rateLimitClass(body: unknown): McpVerbClass;
   /** Requests per minute per caller, by class — what `handle` actually spends against. */
   readonly limits: Readonly<Record<McpVerbClass, number>>;
-  handle(request: Request): Promise<Response>;
+  /** Present exactly when the route was built with `oauth`. */
+  readonly protectedResource?: McpProtectedResource;
+  handle(request: Request, seen?: McpRequestOrigin): Promise<Response>;
 }
 
 const JSON_HEADERS = { 'content-type': 'application/json' } as const;
@@ -118,23 +151,41 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   });
 
   const path = input.path ?? '/mcp';
+  const oauth = input.oauth;
+  if (oauth !== undefined) assertMcpOAuth(oauth);
+  const scopes = input.scopes ?? [];
+  const resourceOf = (request: Request, seen: McpRequestOrigin | undefined): string | undefined =>
+    oauth === undefined
+      ? undefined
+      : resourceUrl(oauth, seen?.origin ?? new URL(request.url).origin, path);
 
   return {
     method: 'POST',
     path,
     limits,
     rateLimitClass: (body) => server.classify(body),
+    ...(oauth === undefined
+      ? {}
+      : {
+          protectedResource: {
+            paths: metadataPaths(path),
+            document: (origin: string) =>
+              protectedResourceMetadata(oauth, resourceUrl(oauth, origin, path), scopes),
+          },
+        }),
 
-    async handle(request: Request): Promise<Response> {
+    async handle(request: Request, seen?: McpRequestOrigin): Promise<Response> {
       // Every authentication answer lands BEFORE the body is read. Parsing first meant a caller
       // holding a rejected token still learned whether its JSON was well formed — `400 parse
       // error` for one payload and `401` for the next is exactly the oracle the 401 exists to
       // remove, and it costs nothing to close: the body is not an input to any of these.
+      const resource = resourceOf(request, seen);
+      const metadataUrl = resource === undefined ? undefined : metadataUrlFor(resource);
       const token = bearerToken(request);
-      if (token === null) return unauthorized();
+      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false));
 
       const resolved = await input.resolveToken(token);
-      if (resolved === null) return unauthorized();
+      if (resolved === null) return unauthorized(bearerChallenge(metadataUrl, true));
       if (!isAgentActor(resolved.actor)) return notAnAgent();
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
@@ -253,7 +304,7 @@ function notAnAgent(): Response {
   );
 }
 
-function unauthorized(): Response {
+function unauthorized(challenge: string): Response {
   return new Response(
     JSON.stringify({
       code: 'X_MCP_PROTOCOL',
@@ -262,7 +313,7 @@ function unauthorized(): Response {
     }),
     {
       status: 401,
-      headers: { ...JSON_HEADERS, 'www-authenticate': 'Bearer realm="ultimate-mcp"' },
+      headers: { ...JSON_HEADERS, 'www-authenticate': challenge },
     },
   );
 }