@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/organization-mcp.ts

@@ -0,0 +1,485 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Icon,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  isReadOnlyPermissionSet,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  type OrganizationAccessPolicy,
+} from "@opengeni/contracts";
+import { stampDelegatedHumanAuthorization } from "@opengeni/core";
+import { z } from "zod";
+
+import type { ActionCatalogEntry } from "./mcp/action-catalog-types";
+import { ACTION_CATALOG } from "./mcp/action-catalog.gen";
+import { ACTION_REQUEST_SCHEMAS } from "./mcp/action-schema-imports.gen";
+import { actionDescription } from "./mcp/action-descriptions";
+
+/* ----------------------------------------------------------------------------
+   The organization MCP server (`/v1/mcp`).
+
+   Every public API action is reachable through three tools: find an action,
+   describe it, run it. A call runs the real route in this process as the
+   caller, so the route's own permission checks decide, exactly as for the
+   app:
+
+   - a person who signed in (MCP OAuth): the request carries the verified
+     person proof, re-resolving their live access and capping it by the
+     connection's access setting on every call;
+   - an organization API key: the request carries that key.
+
+   The proof lives on the exact Request object in process memory; nothing a
+   client sends can create it.
+   -------------------------------------------------------------------------- */
+
+export type OrganizationMcpCaller =
+  | {
+      kind: "person";
+      accountId: string;
+      subjectId: string;
+      access: OrganizationAccessPolicy;
+    }
+  | { kind: "key"; authorization: string; accessKey: string | null };
+
+/**
+ * Requests that only read but are sent as POST (a search query or a file path
+ * in the body). Read only connections may run them; each route still checks
+ * its own read permission.
+ */
+export const READ_ONLY_POST_ACTIONS: ReadonlySet<string> = new Set([
+  "/v1/workspaces/:workspaceId/knowledge/search",
+  "/v1/workspaces/:workspaceId/knowledge/entries/search",
+  "/v1/workspaces/:workspaceId/document-bases/:baseId/search",
+  "/v1/workspaces/:workspaceId/sessions/:sessionId/fs/read",
+  "/v1/workspaces/:workspaceId/sessions/:sessionId/git/diff",
+  "/v1/workspaces/:workspaceId/integrations/preview",
+  "/v1/workspaces/:workspaceId/plugins/preview",
+  "/v1/workspaces/:workspaceId/skills/preview",
+  "/v1/organizations/:organizationId/external-identities/lookup",
+]);
+
+const MAX_RESPONSE_BYTES = 256 * 1024;
+const STREAM_READ_MS = 2_000;
+
+export const OrganizationActionSearchInput = z
+  .object({
+    query: z.string().max(200).default(""),
+    limit: z.number().int().min(1).max(50).default(20),
+    offset: z.number().int().min(0).default(0),
+  })
+  .strict();
+export const OrganizationActionDescribeInput = z
+  .object({ id: z.string().min(1).max(300) })
+  .strict();
+export const OrganizationActionCallInput = z
+  .object({
+    id: z.string().min(1).max(300),
+    pathParameters: z.record(z.string(), z.string().min(1).max(1024)).default({}),
+    query: z
+      .record(
+        z.string(),
+        z.union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number()]))]),
+      )
+      .default({}),
+    body: z.unknown().optional(),
+  })
+  .strict();
+const SearchInput = OrganizationActionSearchInput;
+const DescribeInput = OrganizationActionDescribeInput;
+const CallInput = OrganizationActionCallInput;
+
+const TOOLS = [
+  {
+    name: "opengeni_actions_search",
+    title: "Find Opengeni actions",
+    description:
+      "Search every action available in Opengeni: sessions and chats, workspaces, people, knowledge, files, schedules, connections, models, keys, billing and settings. Returns action ids to describe and call. An empty query lists everything, page by page.",
+    inputSchema: z.toJSONSchema(SearchInput, { io: "input" }),
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "opengeni_action_describe",
+    title: "Describe an Opengeni action",
+    description:
+      "Show an action's method, path, path parameters and the JSON schema of its input, so it can be called correctly.",
+    inputSchema: z.toJSONSchema(DescribeInput, { io: "input" }),
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "opengeni_action_call",
+    title: "Run an Opengeni action",
+    description:
+      "Run one Opengeni action as this connection, with exactly the access it was given. Pass path parameters (for example workspaceId), query parameters and a JSON body. Returns the HTTP status and response.",
+    inputSchema: z.toJSONSchema(CallInput, { io: "input" }),
+    annotations: { readOnlyHint: false, openWorldHint: false },
+  },
+] as const;
+
+/** The brand mark from `apps/web/public/favicon.svg`. */
+const BRAND_MARK_PATH =
+  "M251 83.5966L207 109L163 83.5966L119 109L75 83.5966L141 45.4915A44 44 0 0 1 185 45.4915ZM185.25 172.3642A44.5 44.5 0 0 1 140.75 172.3642L75 134.4034L119 109L163 134.4034L207 109L251 134.4034Z";
+
+function brandMarkSvgDataUri(fill: string): string {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="71 17 184 184" width="184" height="184"><path fill="${fill}" d="${BRAND_MARK_PATH}"/></svg>`;
+  return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+}
+
+/**
+ * MCP `serverInfo.icons` (spec 2025-11-25). Self-contained data URIs work for
+ * every deployment; the web app's PNG is added when its public origin is known.
+ */
+export function organizationMcpIcons(publicOrigin: string | null): Icon[] {
+  const icons: Icon[] = [
+    {
+      src: brandMarkSvgDataUri("#111111"),
+      mimeType: "image/svg+xml",
+      sizes: ["any"],
+      theme: "light",
+    },
+    {
+      src: brandMarkSvgDataUri("#FFFFFF"),
+      mimeType: "image/svg+xml",
+      sizes: ["any"],
+      theme: "dark",
+    },
+  ];
+  if (publicOrigin) {
+    icons.push({
+      src: new URL("/icon-512.png", publicOrigin).href,
+      mimeType: "image/png",
+      sizes: ["512x512"],
+      theme: "light",
+    });
+  }
+  return icons;
+}
+
+export type OrganizationActionContext = {
+  caller: OrganizationMcpCaller;
+  /** This API's own origin; the call never leaves the process. */
+  origin: string;
+  /** The web app's public origin, when configured; serves the PNG icon. */
+  publicOrigin?: string | null;
+  dispatch: (request: Request) => Promise<Response>;
+  signal?: AbortSignal;
+};
+
+export function buildOrganizationMcpServer(input: OrganizationActionContext): Server {
+  const server = new Server(
+    {
+      name: "opengeni",
+      title: "Opengeni",
+      version: "1.0.0",
+      websiteUrl: "https://opengeni.ai",
+      icons: organizationMcpIcons(input.publicOrigin ?? null),
+    },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        "Opengeni actions: use opengeni_actions_search to find what you need, opengeni_action_describe for its inputs, then opengeni_action_call. Most actions take a workspaceId path parameter; list workspaces first (search 'workspaces').",
+    },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((tool) => ({ ...tool, inputSchema: tool.inputSchema as never })),
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+    const args = request.params.arguments ?? {};
+    switch (request.params.name) {
+      case "opengeni_actions_search": {
+        const parsed = SearchInput.safeParse(args);
+        if (!parsed.success) return invalid(parsed.error);
+        return json(searchActions(parsed.data));
+      }
+      case "opengeni_action_describe": {
+        const parsed = DescribeInput.safeParse(args);
+        if (!parsed.success) return invalid(parsed.error);
+        return describeActionResult(parsed.data.id);
+      }
+      case "opengeni_action_call": {
+        const parsed = CallInput.safeParse(args);
+        if (!parsed.success) return invalid(parsed.error);
+        return await callOrganizationAction(input, parsed.data);
+      }
+      default:
+        return failure(`Unknown tool ${request.params.name}.`);
+    }
+  });
+  return server;
+}
+
+export function findAction(id: string): ActionCatalogEntry | undefined {
+  const trimmed = id.trim();
+  return ACTION_CATALOG.find(
+    (entry) => entry.id === trimmed || `${entry.method} ${entry.path}` === trimmed,
+  );
+}
+
+function words(value: string): string[] {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/u)
+    .filter(Boolean);
+}
+
+/** Actions an MCP caller can complete: browser-only ones are left out. */
+const CALLABLE_ACTIONS = ACTION_CATALOG.filter((entry) => !entry.browserOnly);
+const DESCRIPTIONS = new Map(
+  CALLABLE_ACTIONS.map((entry) => [entry.id, actionDescription(entry)] as const),
+);
+
+export function searchActions(input: { query: string; limit: number; offset: number }) {
+  // Singular and plural match ("workspace" finds listWorkspaces).
+  const stem = (word: string) =>
+    word.endsWith("ies") ? `${word.slice(0, -3)}y` : word.replace(/(?<!s)s$/u, "");
+  const wanted = words(input.query).map(stem);
+  // "workspaces" asks for a list; prefer list actions on a plural query.
+  const plural = words(input.query).some((word) => /[^s]s$/u.test(word));
+  const scored = CALLABLE_ACTIONS.map((entry) => {
+    // A word in the action's name matters far more than one in its path:
+    // nearly every path contains "workspaces".
+    const name = words(entry.id).map(stem);
+    const path = [...words(entry.path.replace(/:\w+/g, "")), entry.method.toLowerCase()].map(stem);
+    // A described action also matches the words people use for it
+    // ("pause", "primary", "reset"), below a name match.
+    const described = words(DESCRIPTIONS.get(entry.id) ?? "").map(stem);
+    const score = wanted.reduce(
+      (total, word) =>
+        total +
+        (name.includes(word)
+          ? 4
+          : name.some((token) => token.startsWith(word))
+            ? 3
+            : path.includes(word)
+              ? 1
+              : path.some((token) => token.startsWith(word))
+                ? 0.5
+                : described.includes(word)
+                  ? 0.5
+                  : 0),
+      0,
+    );
+    return {
+      entry,
+      score: score + (plural && score > 0 && name[0] === "list" ? 0.5 : 0),
+      size: name.length,
+    };
+  }).filter((candidate) => wanted.length === 0 || candidate.score > 0);
+  scored.sort(
+    (left, right) =>
+      right.score - left.score ||
+      left.size - right.size ||
+      // On a tie, reads come before writes.
+      Number(left.entry.method !== "GET") - Number(right.entry.method !== "GET") ||
+      left.entry.id.localeCompare(right.entry.id),
+  );
+  return {
+    total: scored.length,
+    offset: input.offset,
+    actions: scored.slice(input.offset, input.offset + input.limit).map(({ entry }) => {
+      const description = DESCRIPTIONS.get(entry.id);
+      return {
+        id: entry.id,
+        method: entry.method,
+        path: entry.path,
+        ...(description ? { description } : {}),
+      };
+    }),
+  };
+}
+
+function pathParameters(path: string): string[] {
+  return [...path.matchAll(/:(\w+)/g)].map((match) => match[1]!);
+}
+
+function schemaFor(name: string): unknown {
+  const candidate = ACTION_REQUEST_SCHEMAS[name];
+  if (!(candidate instanceof z.ZodType)) return null;
+  try {
+    return z.toJSONSchema(candidate, { io: "input", unrepresentable: "any" });
+  } catch {
+    return null;
+  }
+}
+
+/** The describe tool's answer for an action id, or why it can't be used. */
+export function describeActionResult(id: string): CallToolResult {
+  const entry = findAction(id);
+  if (!entry) return failure(`No action "${id}". Search for it first.`);
+  if (entry.browserOnly) return browserOnly(entry);
+  return json(describeAction(entry));
+}
+
+export function describeAction(entry: ActionCatalogEntry) {
+  const reads = entry.method === "GET" || entry.method === "HEAD";
+  const description = actionDescription(entry);
+  return {
+    id: entry.id,
+    method: entry.method,
+    path: entry.path,
+    ...(description ? { description } : {}),
+    pathParameters: pathParameters(entry.path),
+    input: entry.request.map((name) => ({
+      name,
+      in: reads ? "query" : "body",
+      schema: schemaFor(name),
+    })),
+    response: entry.response,
+  };
+}
+
+/** Run one public action in process as the caller; the route's own checks decide. */
+export async function callOrganizationAction(
+  context: OrganizationActionContext,
+  input: z.infer<typeof OrganizationActionCallInput>,
+): Promise<CallToolResult> {
+  const entry = findAction(input.id);
+  if (!entry) return failure(`No action "${input.id}". Search for it first.`);
+  if (entry.browserOnly) return browserOnly(entry);
+  const reads = entry.method === "GET" || entry.method === "HEAD";
+  if (
+    context.caller.kind === "person" &&
+    !reads &&
+    !READ_ONLY_POST_ACTIONS.has(entry.path) &&
+    isReadOnlyPermissionSet(context.caller.access.permissions)
+  ) {
+    return failure("This connection is read only, so it can't change anything.");
+  }
+  let path = entry.path;
+  for (const name of pathParameters(entry.path)) {
+    const value = input.pathParameters[name];
+    if (!value) return failure(`Missing path parameter ${name}.`);
+    // Encoding leaves "." alone, so a dot segment would reach another route.
+    if (value === "." || value === "..") return failure(`Invalid path parameter ${name}.`);
+    path = path.replace(`:${name}`, encodeURIComponent(value));
+  }
+  const url = new URL(path, context.origin);
+  if (url.pathname !== path) return failure("Invalid path parameters.");
+  for (const [key, value] of Object.entries(input.query)) {
+    for (const each of Array.isArray(value) ? value : [value])
+      url.searchParams.append(key, String(each));
+  }
+  const headers = new Headers({
+    accept: "application/json",
+    [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
+  });
+  if (context.caller.kind === "key") {
+    headers.set("authorization", context.caller.authorization);
+    if (context.caller.accessKey) headers.set("x-opengeni-access-key", context.caller.accessKey);
+  }
+  const body = reads ? undefined : JSON.stringify(input.body ?? {});
+  if (body !== undefined) {
+    headers.set("content-type", "application/json");
+    // Exact length: the body-limit middleware otherwise rebuilds the Request,
+    // and the person proof lives on this exact object.
+    headers.set("content-length", String(Buffer.byteLength(body)));
+  }
+  const request = new Request(url, {
+    method: entry.method,
+    headers,
+    ...(body !== undefined ? { body } : {}),
+    ...(context.signal ? { signal: context.signal } : {}),
+    redirect: "manual",
+  });
+  if (context.caller.kind === "person") {
+    stampDelegatedHumanAuthorization(request, {
+      organizationId: context.caller.accountId,
+      subjectId: context.caller.subjectId,
+      permissions: context.caller.access.permissions,
+      workspaceScope: context.caller.access.workspaceScope,
+    });
+  }
+  const response = await context.dispatch(request);
+  return await toolResult(response);
+}
+
+async function toolResult(response: Response): Promise<CallToolResult> {
+  const status = response.status;
+  const location = response.headers.get("location");
+  if (status >= 300 && status < 400 && location) {
+    await response.body?.cancel();
+    return json({
+      status,
+      openInBrowser: location,
+      hint: "Open this link in a browser to finish.",
+    });
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  const result: Record<string, unknown> = { status };
+  if (/text\/event-stream/i.test(contentType)) {
+    result.events = await readStream(response);
+  } else {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const truncated = bytes.byteLength > MAX_RESPONSE_BYTES;
+    const kept = truncated ? bytes.slice(0, MAX_RESPONSE_BYTES) : bytes;
+    if (/json/i.test(contentType) && !truncated) {
+      result.body = JSON.parse(new TextDecoder().decode(kept) || "null");
+    } else if (/^text\/|json|xml|yaml|javascript/i.test(contentType) || contentType === "") {
+      result.body = new TextDecoder().decode(kept);
+    } else {
+      result.contentType = contentType;
+      result.base64 = Buffer.from(kept).toString("base64");
+    }
+    if (truncated)
+      result.truncated = { returnedBytes: MAX_RESPONSE_BYTES, totalBytes: bytes.byteLength };
+  }
+  if (
+    (status === 401 || status === 403) &&
+    /human|browser|cookie|same-origin/i.test(JSON.stringify(result.body ?? ""))
+  ) {
+    result.hint = "This action has to be done by the person in the Opengeni app in a browser.";
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    ...(status >= 400 ? { isError: true } : {}),
+  };
+}
+
+async function readStream(response: Response): Promise<string> {
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const decoder = new TextDecoder();
+  let text = "";
+  const deadline = Date.now() + STREAM_READ_MS;
+  try {
+    while (Date.now() < deadline && text.length < MAX_RESPONSE_BYTES) {
+      const next = await Promise.race([
+        reader.read(),
+        new Promise<{ done: true; value: undefined }>((resolve) =>
+          setTimeout(
+            () => resolve({ done: true, value: undefined }),
+            Math.max(0, deadline - Date.now()),
+          ),
+        ),
+      ]);
+      if (next.done) break;
+      text += decoder.decode(next.value, { stream: true });
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+  return text;
+}
+
+function json(value: unknown): CallToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+
+/** A browser-only action: say why, and that the person has to do it. */
+function browserOnly(entry: ActionCatalogEntry): CallToolResult {
+  return failure(
+    `${entry.id} isn't available to connected agents or API keys: ${entry.browserOnly}. The person has to do it in the Opengeni app in a browser.`,
+  );
+}
+
+function failure(message: string): CallToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function invalid(error: z.ZodError): CallToolResult {
+  return failure(`Invalid input: ${z.prettifyError(error)}`);
+}

package/src/prepared-mcp-actor.ts

@@ -0,0 +1,154 @@
+import {
+  DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  readTurnExecutionPolicyV1,
+  resolveAgentToolFamilies,
+  type AccessGrant,
+} from "@opengeni/contracts";
+import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import {
+  getActiveSessionTurnForExecution,
+  getAttemptToolCatalog,
+  getSession,
+  requireWorkspace,
+  lockTurnAttemptWriteFenceTx,
+  resolveInitiatingHuman,
+  type Database,
+} from "@opengeni/db";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import {
+  externalActorContinuationForAuthorization,
+  hasPermission,
+  isDeveloperSetupGrant,
+  requireSessionAuthorization,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { requireConnectOwnerAuthority } from "./integrations/connect-authority";
+import {
+  isPersonalConnectionOwnerPrincipal,
+  isPersonalConnectionOwnerSubject,
+} from "./connection-ownership";
+import { codemodeAuthorityForGrant, requireMatchingCodemodeCatalog } from "./codemode";
+import { PREPARED_MCP_PERMISSIONS, preparedMcpProxyPermissions } from "./prepared-mcp-permissions";
+import { resolveSessionFirstPartyMcpTools } from "@opengeni/config";
+import { HTTPException } from "hono/http-exception";
+
+/** The normal browser and the exact agent attempt share Connect storage and
+ * verification. This adapter is ONLY for prepared MCP keys, never interactive
+ * OAuth, arbitrary native connections, or a caller-supplied owner identity. */
+export async function connectRequestActor(
+  deps: ApiRouteDeps,
+  authorization: AccessGrantAuthorization,
+) {
+  if (!authorization.contextIntegrity)
+    throw new HTTPException(403, { message: "Verified Connect authority required" });
+  const grant = authorization.grant;
+  const continuation = externalActorContinuationForAuthorization(authorization);
+  const ordinary = {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    subjectId: grant.subjectId,
+    personalOwnerVerified: isPersonalConnectionOwnerPrincipal(authorization),
+    ...(continuation ? { externalContinuation: continuation } : {}),
+  };
+  if (grant.principalKind !== "agent_attempt")
+    return {
+      scope: ordinary,
+      grant,
+      beforeOperation: undefined,
+      preparedOnly: false,
+    };
+  const authority = codemodeAuthorityForGrant(grant);
+  if (
+    !authority ||
+    isDeveloperSetupGrant(grant) ||
+    PREPARED_MCP_PERMISSIONS.some((permission) => !hasPermission(grant.permissions, permission))
+  )
+    throw new HTTPException(403, { message: "Prepared MCP setup authority required" });
+  await requireSessionAuthorization(deps, grant, {
+    sessionId: authority.sessionId,
+    operation: "session.first_party_mcp.call",
+    surface: "first_party_mcp",
+  });
+  const turn = await getActiveSessionTurnForExecution(
+    deps.db,
+    authority.workspaceId,
+    authority.sessionId,
+  );
+  // No creator, current browser user, raw metadata, or historical fallback.
+  const owner = turn?.initiatingHumanSubjectId;
+  if (
+    !turn ||
+    turn.id !== authority.turnId ||
+    turn.activeAttemptId !== authority.attemptId ||
+    turn.executionGeneration !== authority.executionGeneration ||
+    !owner ||
+    !isPersonalConnectionOwnerSubject(owner)
+  )
+    throw new HTTPException(403, { message: "Prepared MCP setup requires an exact causal owner" });
+  const scope = {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    subjectId: owner,
+    personalOwnerVerified: true,
+  };
+  const beforeOperation = async (tx: Database) => {
+    // Organization policy is already locked by the caller. Live membership
+    // precedes workspace/session/turn locks and remains held through commit.
+    for (const permission of PREPARED_MCP_PERMISSIONS)
+      await requireConnectOwnerAuthority(tx, scope, permission);
+    const fence = await lockTurnAttemptWriteFenceTx(tx, authority);
+    if (
+      !fence.allowed ||
+      fence.turn.initiatingHumanSubjectId !== owner ||
+      fence.turn.accountId !== grant.accountId
+    )
+      throw new HTTPException(403, { message: "The setup execution attempt is no longer active" });
+    for (const metadata of [fence.turn.metadata, fence.session.metadata]) {
+      const policy = readTurnExecutionPolicyV1(metadata);
+      if (policy.kind === "valid" && policy.policy.credentialRestriction)
+        throw new HTTPException(403, { message: "This execution cannot configure credentials" });
+    }
+    const session = await getSession(tx, authority.workspaceId, authority.sessionId);
+    const catalog = requireMatchingCodemodeCatalog(
+      authority,
+      await getAttemptToolCatalog(tx, authority),
+    );
+    const selected =
+      session &&
+      resolveSessionFirstPartyMcpTools(
+        deps.settings,
+        session,
+        (await requireWorkspace(tx, authority.workspaceId)).settings,
+      );
+    const admitted =
+      session &&
+      preparedMcpProxyPermissions(
+        catalog,
+        session.firstPartyMcpPermissions ?? [...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS],
+      );
+    if (
+      !selected?.includes("custom_mcp_setup_request") ||
+      !resolveAgentToolFamilies(session?.agent).allowsFirstPartyTool("custom_mcp_setup_request") ||
+      !admitted ||
+      PREPARED_MCP_PERMISSIONS.some((permission) => !admitted.includes(permission)) ||
+      !(await resolveInitiatingHuman(tx, scope, owner, authority.turnId))
+    )
+      throw new HTTPException(403, {
+        message: "Prepared MCP setup is not allowed by this attempt",
+      });
+  };
+  await withOrganizationIntegrationPolicyFence(deps.db, scope, (tx) => beforeOperation(tx));
+  // Internal resource lookup only. The authenticated principal stays an agent;
+  // no human_session token or ambient personal-connection delegation is minted.
+  const ownerGrant: AccessGrant = { ...grant, subjectId: owner };
+  return { scope, grant: ownerGrant, beforeOperation, preparedOnly: true };
+}
+
+export function assertAgentPreparedConnect(
+  actor: { preparedOnly: boolean },
+  attempt: Pick<ConnectAttempt, "providerId" | "mcpSetup">,
+): void {
+  if (actor.preparedOnly && (attempt.providerId !== "mcp-headers" || !attempt.mcpSetup))
+    throw new HTTPException(403, { message: "Agent setup is limited to prepared MCP credentials" });
+}

package/src/prepared-mcp-permissions.ts

@@ -0,0 +1,38 @@
+import type { AttemptToolCatalog, Permission } from "@opengeni/contracts";
+
+export const PREPARED_MCP_PERMISSIONS = [
+  "connections:read",
+  "connections:write",
+  "capabilities:manage",
+] as const satisfies readonly Permission[];
+
+/** Only the existing native Connect resource can receive setup permissions.
+ * This never expands SDK access to unrelated credential or settings routes. */
+export function isPreparedMcpConnectPath(path: string, method: string): boolean {
+  const match =
+    /^\/v1\/workspaces\/[^/]+\/connect\/attempts(?:\/([0-9a-f-]{36})(?:\/(advance|cancel))?)?$/.exec(
+      path,
+    );
+  return Boolean(
+    match && (method === "GET" ? !match[2] : method === "POST" && (!match[1] || match[2])),
+  );
+}
+
+/** The accepted tool must be present without an outstanding human-review gate.
+ * A session/settings edit can remove authority but cannot add it to this attempt. */
+export function preparedMcpProxyPermissions(
+  catalog: AttemptToolCatalog,
+  livePermissions: readonly Permission[],
+): Permission[] {
+  const entry = catalog.entries.find(
+    (item) =>
+      item.identity.serverId === "opengeni" &&
+      item.identity.toolName === "custom_mcp_setup_request",
+  );
+  if (!entry || entry.approval !== "none") return [];
+  return PREPARED_MCP_PERMISSIONS.filter(
+    (permission) =>
+      catalog.firstPartyMcpPermissions?.includes(permission) &&
+      livePermissions.includes(permission),
+  );
+}