@vellumai/assistant 0.12.5-dev.202609252115.c8e1713 → 0.12.5-dev.202609252314.2f8433a

package/ARCHITECTURE.md

@@ -49,6 +49,8 @@ Resource pressure monitoring reports sustained CPU/memory pressure on platform-h
 
 When the container hits its memory limit, the kernel kills the process with the highest `oom_score` (memory share plus `oom_score_adj`). `src/util/oom-priority.ts` steers that choice so the assistant is never the victim of a runaway tool: the daemon sets itself to -700 as the first thing in `runDaemon`, before any spawn. Children inherit the parent's value at fork, so every spawn path resets its child: shell children get +1000 from the Linux prefix in `buildShellInvocation` (`packages/environments`), desktop children and ACP agents and terminals get +1000 from `withOomScoreAdj`, an `sh -c ... exec` wrapper that keeps pid and process group, and workers, the embedding worker, and Qdrant get 0 from a parent-side write right after spawn (the resource monitor gets -500 so it outlives everything but the daemon and records the kill). The monitor also sweeps the daemon's descendants every few seconds (`src/monitoring/oom-inheritance-sweep.ts`) and writes 0 over any negative value it finds, logging the comm, so a spawn path that forgets the reset degrades to a few seconds of inherited protection instead of a protected runaway. Bundled plugins (the memory plugin's rerank worker, for one) rely on the sweep rather than importing the helper, since the plugin import boundary forbids reaching outside the plugin. Raising never needs a capability; lowering needs `CAP_SYS_RESOURCE`, which the platform grants and self-hosted Docker does not, where the daemon simply stays at 0. Nothing here caps a single process or acts early: it only decides who dies once the kernel has to kill.
 
+**Verification telemetry:** the resource monitor reports kernel OOM kills in the container as a `watchdog` event with `check_name` `oom_kill` (`src/monitoring/oom-kill-reporter.ts`). It reads the kernel log through `dmesg` (the `/dev/kmsg` device is not mounted in the container; `dmesg` uses the syslog syscall, which the Kata profile permits) when the cgroup `memory.events` kill counter moves, on its first scan after start (the kill that took the daemon down restarts the monitor with it), and once a minute as a fallback. The kernel log is shared by every container on that kernel and cgroup paths read `/` from inside, so attribution is by the counter: a move of N claims the N most recent new kills; the first scan and hosts without the counter claim every new kill and say so with `attribution: "kernel_log"`. The `detail` bag lists each victim's comm, `oom_score_adj` and resident size, the cgroup memory figures at the time, and `killed_daemon`, detected by the daemon's -700 score rather than a pid the restart has since replaced; where the log is unreadable a counter move still yields a victimless event. A cursor (kernel boot id plus last log timestamp) on the monitor data dir advances only after the event is queued, so a telemetry store outage delays a report rather than losing one, and resets when the kernel reboots.
+
 ### Single-Header JWT Auth Model
 
 All HTTP API requests use a single `Authorization: Bearer <jwt>` header for authentication. The JWT carries identity, permissions, and policy versioning in a unified token.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.5-dev.202609252115.c8e1713",
+  "version": "0.12.5-dev.202609252314.2f8433a",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/oauth2-gateway-transport.test.ts

@@ -48,6 +48,8 @@ let mockOAuthCallbackUrl = "";
 // getPublicBaseUrl.
 mock.module("../inbound/public-ingress-urls.js", () => ({
   getOAuthCallbackUrl: () => mockOAuthCallbackUrl,
+  getMcpOAuthClientMetadataUrl: () =>
+    "http://localhost/oauth/client-metadata.json",
   getPublicBaseUrl: (config?: { ingress?: { publicBaseUrl?: string } }) => {
     const url = config?.ingress?.publicBaseUrl ?? "";
     if (!url) {

package/src/__tests__/public-ingress-urls.test.ts

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { setIngressPublicBaseUrl } from "../config/env.js";
 import { IngressConfigSchema } from "../config/schemas/ingress.js";
 import {
+  getMcpOAuthClientMetadataUrl,
   getOAuthCallbackUrl,
   getPublicBaseUrl,
   getTelegramWebhookUrl,
@@ -307,6 +308,31 @@ describe("getOAuthCallbackUrl", () => {
     });
     expect(url).toBe("https://example.com/webhooks/oauth/callback");
   });
+
+  test("canonicalizes the base before building OAuth URLs", () => {
+    const config = {
+      ingress: {
+        publicBaseUrl: "https://EXAMPLE.com:443/a/../assistant-123///",
+      },
+    };
+
+    expect(getOAuthCallbackUrl(config)).toBe(
+      "https://example.com/assistant-123/webhooks/oauth/callback",
+    );
+    expect(getMcpOAuthClientMetadataUrl(config)).toBe(
+      "https://example.com/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});
+
+describe("getMcpOAuthClientMetadataUrl", () => {
+  test("builds the public metadata URL", () => {
+    expect(
+      getMcpOAuthClientMetadataUrl({
+        ingress: { publicBaseUrl: "https://example.com/assistant-123/" },
+      }),
+    ).toBe("https://example.com/assistant-123/oauth/client-metadata.json");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/cli/commands/browser.ts

@@ -214,8 +214,7 @@ function attachOperationAction(
       opts.output &&
       result.screenshots?.length
     ) {
-      const screenshot = result.screenshots[0];
-      const buffer = Buffer.from(screenshot.data, "base64");
+      const buffer = Buffer.from(result.screenshots[0].data, "base64");
       try {
         writeFileSync(String(opts.output), buffer);
       } catch (err) {

package/src/cli/lib/__tests__/plugin-catalog-visibility.test.ts

@@ -33,6 +33,7 @@ describe("filterPluginCatalogByFeatureFlags", () => {
       "ramp",
       "semrush",
       "typeform",
+      "upwork",
       "notion",
     ]);
 
@@ -56,6 +57,7 @@ describe("filterPluginCatalogByFeatureFlags", () => {
       "ramp",
       "semrush",
       "typeform",
+      "upwork",
     ]);
 
     const result = filterPluginCatalogByFeatureFlags(input, () => true);

package/src/cli/lib/plugin-artifact.ts

@@ -89,8 +89,9 @@ export function parsePluginArtifact(
   if (typeof vellum !== "object" || vellum === null || Array.isArray(vellum)) {
     return null;
   }
-  const artifact = (vellum as Record<string, unknown>).artifact;
-  const parsed = PluginArtifactSchema.safeParse(artifact);
+  const parsed = PluginArtifactSchema.safeParse(
+    (vellum as Record<string, unknown>).artifact,
+  );
   if (!parsed.success) {
     return null;
   }

package/src/cli/lib/plugin-catalog-visibility.ts

@@ -10,6 +10,7 @@ const MCP_CATALOG_QA_INTEGRATION_NAMES = new Set([
   "ramp",
   "semrush",
   "typeform",
+  "upwork",
 ]);
 
 export type PluginCatalogFeatureFlagResolver = (key: string) => boolean;

package/src/config/feature-flag-registry.json

@@ -343,7 +343,7 @@
       "scope": "assistant",
       "key": "mcp-catalog-qa-integrations",
       "label": "MCP Catalog QA Integrations",
-      "description": "Show Gamma, Guru, Intercom, Ramp, Semrush, and Typeform in the installable plugin catalog while their OAuth flows are validated. When off, catalog search, detail, and install-by-name cannot resolve them. Existing installed connections remain available.",
+      "description": "Show Gamma, Guru, Intercom, Ramp, Semrush, Typeform, and Upwork in the installable plugin catalog while their OAuth flows are validated. When off, catalog search, detail, and install-by-name cannot resolve them. Existing installed connections remain available.",
       "defaultEnabled": false
     },
     {

package/src/inbound/__tests__/oauth-callback-url.test.ts

@@ -21,19 +21,42 @@ mock.module("../platform-callback-registration.js", () => ({
 
 mock.module("../public-ingress-urls.js", () => ({
   getOAuthCallbackUrl: () => "https://direct.example/webhooks/oauth/callback",
+  getMcpOAuthClientMetadataUrl: () =>
+    "https://direct.example/oauth/client-metadata.json",
 }));
 
 mock.module("../../config/loader.js", () => ({
   loadConfig: () => ({}),
 }));
 
-const { OAUTH_CALLBACK_PATH, resolveOauthCallbackUrl } =
-  await import("../oauth-callback-url.js");
+const {
+  OAUTH_CALLBACK_PATH,
+  resolveMcpOAuthClientMetadataUrl,
+  resolveOauthCallbackUrl,
+} = await import("../oauth-callback-url.js");
 
 afterEach(() => {
   resolveCallbackUrl.mockClear();
 });
 
+describe("resolveMcpOAuthClientMetadataUrl", () => {
+  test("returns the metadata URL for the exact direct HTTPS callback", () => {
+    expect(
+      resolveMcpOAuthClientMetadataUrl(
+        "https://direct.example/webhooks/oauth/callback",
+      ),
+    ).toBe("https://direct.example/oauth/client-metadata.json");
+  });
+
+  test("returns undefined for a callback served somewhere else", () => {
+    expect(
+      resolveMcpOAuthClientMetadataUrl(
+        "https://platform.example/v1/gateway/callbacks/assistant-123/webhooks/oauth/callback",
+      ),
+    ).toBeUndefined();
+  });
+});
+
 describe("resolveOauthCallbackUrl", () => {
   test("returns whatever the shared resolver decides", async () => {
     await expect(resolveOauthCallbackUrl()).resolves.toEqual(

package/src/inbound/oauth-callback-url.ts

@@ -18,7 +18,10 @@
 
 import { loadConfig } from "../config/loader.js";
 import { resolveCallbackUrl } from "./platform-callback-registration.js";
-import { getOAuthCallbackUrl } from "./public-ingress-urls.js";
+import {
+  getMcpOAuthClientMetadataUrl,
+  getOAuthCallbackUrl,
+} from "./public-ingress-urls.js";
 
 /**
  * Path the gateway serves the shared OAuth callback on.
@@ -59,3 +62,29 @@ export async function resolveOauthCallbackUrl(): Promise<string> {
     OAUTH_REGISTRATION_TYPE,
   );
 }
+
+/**
+ * Return the public Client ID Metadata Document URL when it is compatible
+ * with the callback selected for this flow.
+ *
+ * A URL-based client id must be HTTPS, and its document must publish the exact
+ * redirect URI used by the authorization request. The gateway document is
+ * derived from public ingress, so a platform-relayed callback cannot use it.
+ * Returning undefined preserves Dynamic Client Registration as the SDK's
+ * fallback in either case.
+ */
+export function resolveMcpOAuthClientMetadataUrl(
+  redirectUrl: string,
+): string | undefined {
+  try {
+    const config = loadConfig();
+    if (getOAuthCallbackUrl(config) !== redirectUrl) {
+      return undefined;
+    }
+
+    const metadataUrl = getMcpOAuthClientMetadataUrl(config);
+    return new URL(metadataUrl).protocol === "https:" ? metadataUrl : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/inbound/public-ingress-urls.ts

@@ -27,6 +27,10 @@
  * All public-facing ingress URL construction is centralized here.
  */
 
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadataUrl,
+} from "@vellumai/service-contracts/mcp-oauth";
 import {
   buildTwilioMediaStreamUrl,
   buildTwilioStatusWebhookUrl,
@@ -160,8 +164,14 @@ export function getTwilioMediaStreamUrl(config: IngressConfig): string {
  * Build the OAuth callback URL.
  */
 export function getOAuthCallbackUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/oauth/callback`;
+  return buildMcpOAuthCallbackUrl(getPublicBaseUrl(config));
+}
+
+/**
+ * Build the public Client ID Metadata Document URL for MCP OAuth.
+ */
+export function getMcpOAuthClientMetadataUrl(config: IngressConfig): string {
+  return buildMcpOAuthClientMetadataUrl(getPublicBaseUrl(config));
 }
 
 /**