agor-live 0.22.0 → 0.23.2

package/dist/daemon/mcp/tools/mcp-servers.js

@@ -64,6 +64,12 @@ var init_executor_read_impersonation = __esm({
   }
 });
 
+// src/mcp/tools/mcp-servers.ts
+import {
+  isReservedMCPCustomHeaderName,
+  isValidMCPHeaderName
+} from "@agor/core/tools/mcp/http-headers";
+
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -14578,6 +14584,16 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// src/mcp/resolve-ids.ts
+async function resolveSessionId(ctx, id) {
+  const entity = await ctx.app.service("sessions").get(id, ctx.baseServiceParams);
+  return entity.session_id;
+}
+async function resolveMcpServerId(ctx, id) {
+  const entity = await ctx.app.service("mcp-servers").get(id, ctx.baseServiceParams);
+  return entity.mcp_server_id;
+}
+
 // src/mcp/schema.ts
 function suffixExample(example) {
   return example ? ` Example: ${example}` : "";
@@ -14592,6 +14608,11 @@ function mcpOptionalString(fieldName, description) {
     error: `${fieldName} must be a string when provided.`
   }).optional().describe(description);
 }
+function mcpOptionalNonEmptyString(fieldName, description) {
+  return external_exports.string({
+    error: `${fieldName} must be a string when provided.`
+  }).min(1, `${fieldName} cannot be empty when provided.`).optional().describe(description);
+}
 function mcpOptionalNonBlankString(fieldName, description) {
   return external_exports.string({
     error: `${fieldName} must be a string when provided.`
@@ -14612,6 +14633,14 @@ function mcpRequiredPositiveInt(fieldName, description) {
     error: `${fieldName} is required and must be a positive integer.`
   }).int(`${fieldName} must be an integer.`).positive(`${fieldName} must be greater than 0.`).describe(description);
 }
+function mcpOptionalPositiveInt(fieldName, description) {
+  return external_exports.number({
+    error: `${fieldName} must be a positive integer when provided.`
+  }).int(`${fieldName} must be an integer.`).positive(`${fieldName} must be greater than 0.`).optional().describe(description);
+}
+function mcpLimit(defaultValue = 50) {
+  return mcpOptionalPositiveInt("limit", `Maximum number of results (default: ${defaultValue})`);
+}
 
 // src/mcp/server.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -14624,7 +14653,11 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/mcp/tokens.ts
 import { MCP_TOKEN } from "@agor/core/config";
-import { generateId, SessionRepository, shortId } from "@agor/core/db";
+import {
+  generateId,
+  SessionRepository,
+  shortId
+} from "@agor/core/db";
 import {
   MCP_TOKEN_AUDIENCE,
   MCP_TOKEN_ISSUER
@@ -14645,6 +14678,7 @@ var DOMAIN_DESCRIPTIONS = {
   users: "User accounts, profiles, preferences, and administration",
   analytics: "Usage and cost tracking leaderboard",
   "mcp-servers": "External MCP server configuration and OAuth management",
+  gateway: "Gateway channels for Slack, GitHub, Teams, and other message integrations",
   proxies: "Configured HTTP proxies for third-party APIs (Shortcut, Linear, Jira, etc.)",
   widgets: "In-conversation interactive widgets \u2014 agents render small forms/buttons inline in the transcript to capture user input that never enters the LLM context",
   knowledge: "DB-backed markdown knowledge documents, version history, search, and graph links",
@@ -14712,7 +14746,7 @@ var AgorRuntimeSchema = external_exports.object({
 
 // src/mcp/tools/branches.ts
 import { existsSync } from "fs";
-import { isBranchRbacEnabled } from "@agor/core/config";
+import { isBranchRbacEnabled, loadConfig } from "@agor/core/config";
 import { BranchRepository as BranchRepository2, shortId as shortId3 } from "@agor/core/db";
 import { BRANCH_PERMISSION_LEVELS as BRANCH_PERMISSION_LEVELS2, getAssistantConfig, isAssistant } from "@agor/core/types";
 import { computeZoneRelativePosition } from "@agor/core/utils/board-placement";
@@ -14721,12 +14755,211 @@ import { normalizeOptionalHttpUrl } from "@agor/core/utils/url";
 // src/mcp/tools/cards.ts
 import { BoardObjectRepository } from "@agor/core/db";
 
+// src/mcp/tools/gateway-channels.ts
+import {
+  BranchRepository as BranchRepository3,
+  GatewayChannelRepository,
+  SessionRepository as SessionRepository2,
+  ThreadSessionMapRepository
+} from "@agor/core/db";
+import {
+  buildSlackManifest,
+  getConnector,
+  requiredBotEvents,
+  requiredBotScopes
+} from "@agor/core/gateway";
+import {
+  GATEWAY_REDACTED_SENTINEL,
+  GATEWAY_SENSITIVE_CONFIG_FIELDS,
+  getRequiredSecretFields,
+  hasMinimumRole as hasMinimumRole2,
+  ROLES as ROLES2
+} from "@agor/core/types";
+var configSchema = external_exports.record(external_exports.string(), external_exports.unknown()).describe(
+  "Platform-specific gateway configuration. Secrets are stored encrypted and returned redacted. Prefer env/template references for shared credentials where the connector supports them."
+);
+var outboundTargetSchema = external_exports.string().trim().regex(
+  /^(channel:[^:\s]+|channel_name:[^\s]+|#[^\s]+|(?:email:|user_email:)?[^@\s]+@[^@\s]+\.[^@\s]+)$/
+).describe(
+  "Slack outbound target for v0: channel:C123, #project-updates, channel_name:project-updates, or user@example.com. Thread targets are intentionally not supported."
+);
+var envVarSchema = external_exports.strictObject({
+  key: mcpRequiredString("agenticConfig.envVars[].key", "Environment variable name"),
+  value: mcpRequiredString(
+    "agenticConfig.envVars[].value",
+    `Environment variable value. Prefer references/templates over raw secrets. Existing redacted values may be passed as '${GATEWAY_REDACTED_SENTINEL}' on update to preserve them.`
+  ),
+  forceOverride: external_exports.boolean().optional().describe("When true, channel value wins over user env vars. Defaults to false.")
+});
+var agenticConfigSchema = external_exports.strictObject({
+  agent: external_exports.enum(["claude-code", "claude-code-cli", "codex", "gemini", "opencode", "copilot", "cursor"]).describe("Agent used for sessions created from this gateway channel."),
+  permissionMode: external_exports.enum([
+    "default",
+    "acceptEdits",
+    "bypassPermissions",
+    "plan",
+    "dontAsk",
+    "autoEdit",
+    "yolo",
+    "ask",
+    "auto",
+    "on-failure",
+    "allow-all"
+  ]).optional().describe("Permission mode for spawned sessions."),
+  modelConfig: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe("Agent model configuration."),
+  mcpServerIds: external_exports.array(external_exports.string().min(1)).optional().describe("MCP server IDs to attach to gateway-created sessions."),
+  codexSandboxMode: external_exports.enum(["read-only", "workspace-write", "danger-full-access"]).optional().describe("Codex sandbox mode for Codex gateway sessions."),
+  codexApprovalPolicy: external_exports.enum(["untrusted", "on-failure", "on-request", "never"]).optional().describe("Codex approval policy for Codex gateway sessions."),
+  codexNetworkAccess: external_exports.boolean().optional().describe("Allow Codex network access."),
+  envVars: external_exports.array(envVarSchema).optional().describe("Gateway-level env vars. Values are redacted in responses.")
+}).describe("Agent/session defaults for conversations created through this gateway channel.");
+var gatewayChannelCreateSchema = external_exports.strictObject({
+  name: mcpRequiredString("name", 'Human-readable channel name, e.g. "Engineering Slack".'),
+  channelType: external_exports.enum(["slack", "github", "teams", "discord", "whatsapp", "telegram"]).default("slack").describe("Gateway platform type. Current active connectors are slack, github, and teams."),
+  targetBranchId: mcpRequiredId(
+    "targetBranchId",
+    "Branch",
+    "Branch/worktree ID that this gateway channel prompts."
+  ),
+  agorUserId: mcpOptionalId(
+    "agorUserId",
+    "User",
+    "Agor user ID whose identity is used when platform-user alignment is disabled."
+  ),
+  enabled: external_exports.boolean().optional().describe("Whether the channel is active. Defaults to true."),
+  config: configSchema,
+  agenticConfig: agenticConfigSchema.optional()
+}).superRefine((value, issue2) => {
+  const config2 = value.config ?? {};
+  if (value.enabled !== false) {
+    const requiredSecretMessages = {
+      bot_token: "config.bot_token is required for Slack. Prefer a bot token stored outside the transcript when possible.",
+      app_token: "config.app_token is required for Slack Socket Mode.",
+      private_key: "config.private_key is required for GitHub gateway channels.",
+      app_password: "config.app_password is required for Teams gateway channels."
+    };
+    for (const field of getRequiredSecretFields(value.channelType, config2)) {
+      if (!config2[field]) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["config", field],
+          message: requiredSecretMessages[field] ?? `config.${field} is required for ${value.channelType} gateway channels.`
+        });
+      }
+    }
+  }
+  if (value.channelType === "github") {
+    for (const field of ["app_id", "installation_id", "watch_repos"]) {
+      if (!config2[field]) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["config", field],
+          message: `config.${field} is required for GitHub gateway channels.`
+        });
+      }
+    }
+  }
+  if (value.channelType === "teams" && !config2.app_id) {
+    issue2.addIssue({
+      code: "custom",
+      path: ["config", "app_id"],
+      message: "config.app_id is required for Teams gateway channels."
+    });
+  }
+  if (value.channelType === "slack" && config2.align_slack_users !== true && !value.agorUserId) {
+    issue2.addIssue({
+      code: "custom",
+      path: ["agorUserId"],
+      message: "Run-as-selected-user needs agorUserId \u2014 set config.align_slack_users:true to align by email, or pass agorUserId."
+    });
+  }
+});
+var slackThreadHistorySchema = external_exports.strictObject({
+  sessionId: mcpOptionalId(
+    "sessionId",
+    "Session",
+    "Preferred: resolve the Slack thread mapping from an accessible Agor session ID (UUIDv7 or short ID). If provided, gatewayChannelId/threadId are ignored."
+  ),
+  gatewayChannelId: mcpOptionalId(
+    "gatewayChannelId",
+    "Gateway channel",
+    "Explicit Slack gateway channel ID (UUIDv7 or short ID). Required when sessionId is omitted."
+  ),
+  threadId: mcpOptionalNonEmptyString(
+    "threadId",
+    "Explicit Slack thread ID in Agor gateway format, e.g. C123-171234.000100. Required when sessionId is omitted."
+  ),
+  oldestTs: mcpOptionalNonEmptyString(
+    "oldestTs",
+    "Optional Slack oldest timestamp bound, e.g. 171234.000100."
+  ),
+  latestTs: mcpOptionalNonEmptyString(
+    "latestTs",
+    "Optional Slack latest timestamp bound, e.g. 171235.000200."
+  ),
+  inclusive: external_exports.boolean().optional().describe("Whether Slack should include messages exactly at oldest/latest bounds."),
+  limit: mcpLimit(50).describe("Maximum Slack messages to request (default: 50, max: 200)."),
+  includeBotMessages: external_exports.boolean().optional().describe("Include Slack bot messages in the returned history. Defaults to false."),
+  format: external_exports.enum(["messages", "markdown"]).optional().describe(
+    'Response body format. "messages" returns normalized JSON; "markdown" returns a transcript string.'
+  )
+}).superRefine((value, issue2) => {
+  if (value.sessionId) return;
+  if (!value.gatewayChannelId) {
+    issue2.addIssue({
+      code: "custom",
+      path: ["gatewayChannelId"],
+      message: "gatewayChannelId is required when sessionId is omitted."
+    });
+  }
+  if (!value.threadId) {
+    issue2.addIssue({
+      code: "custom",
+      path: ["threadId"],
+      message: "threadId is required when sessionId is omitted."
+    });
+  }
+});
+var gatewayChannelUpdateSchema = external_exports.strictObject({
+  gatewayChannelId: mcpRequiredId(
+    "gatewayChannelId",
+    "Gateway channel",
+    "Gateway channel ID (UUIDv7 or short ID)"
+  ),
+  name: mcpOptionalNonEmptyString("name", "New human-readable channel name."),
+  channelType: external_exports.enum(["slack", "github", "teams", "discord", "whatsapp", "telegram"]).optional().describe("Gateway platform type. Changing this should include compatible config."),
+  targetBranchId: mcpOptionalId("targetBranchId", "Branch", "New target branch/worktree ID."),
+  agorUserId: mcpOptionalId("agorUserId", "User", "New run-as Agor user ID."),
+  enabled: external_exports.boolean().optional().describe("Enable/disable the channel."),
+  config: configSchema.optional().describe(
+    `Partial platform config to merge. Send '${GATEWAY_REDACTED_SENTINEL}' or omit sensitive fields to preserve existing secrets; send a new value to rotate.`
+  ),
+  agenticConfig: agenticConfigSchema.nullable().optional().describe("Replace agent/session defaults. null clears the gateway agentic config.")
+});
+var slackManifestGenerateSchema = external_exports.strictObject({
+  appName: mcpRequiredString("appName", 'Slack app display name, e.g. "Agor".'),
+  botDisplayName: mcpOptionalNonEmptyString(
+    "botDisplayName",
+    "Bot user display name. Defaults to appName."
+  ),
+  publicChannels: external_exports.boolean().default(false).describe("Listen in public channels (#channel) via @mention."),
+  privateChannels: external_exports.boolean().default(false).describe("Listen in private channels (groups) via @mention."),
+  groupDms: external_exports.boolean().default(false).describe("Listen in group DMs (multi-person IMs) via @mention."),
+  alignUsers: external_exports.boolean().default(true).describe(
+    "Resolve Slack user email \u2192 Agor user (adds the users:read.email scope). Defaults to true: each Slack user runs as their matched Agor account and unmatched users are rejected, so no fixed run-as user is needed. Set false to run every message as one fixed Agor user (then pass agorUserId to agor_gateway_channels_create)."
+  ),
+  outbound: external_exports.boolean().default(false).describe("Proactive outbound: post to channels by name and DM users by email."),
+  restrictToChannelIds: external_exports.array(external_exports.string().min(1)).optional().describe(
+    "Slack channel ID whitelist. Maps to config.allowed_channel_ids when you call agor_gateway_channels_create; it does NOT change the manifest scopes or events."
+  )
+});
+
 // src/mcp/tools/knowledge.ts
 import { createHash, randomUUID } from "crypto";
 import fs2 from "fs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import path3 from "path";
-import { BranchRepository as BranchRepository4, KnowledgeNamespaceRepository as KnowledgeNamespaceRepository2 } from "@agor/core/db";
+import { BranchRepository as BranchRepository5, KnowledgeNamespaceRepository as KnowledgeNamespaceRepository2 } from "@agor/core/db";
 import { NotFound as NotFound2 } from "@agor/core/feathers";
 import {
   buildKnowledgeDocumentUri,
@@ -14752,14 +14985,14 @@ import { unified } from "unified";
 
 // src/services/assistant-knowledge.ts
 import {
-  BranchRepository as BranchRepository3,
+  BranchRepository as BranchRepository4,
   KnowledgeNamespaceRepository,
   shortId as shortId4
 } from "@agor/core/db";
 import { getAssistantConfig as getAssistantConfig2, isAssistant as isAssistant2 } from "@agor/core/types";
 
 // src/services/knowledge-access.ts
-import { hasMinimumRole as hasMinimumRole2, ROLES as ROLES2 } from "@agor/core/types";
+import { hasMinimumRole as hasMinimumRole3, ROLES as ROLES3 } from "@agor/core/types";
 
 // src/utils/branch-workspace-path.ts
 import fs from "fs";
@@ -14908,16 +15141,18 @@ import {
   asc,
   desc,
   eq,
-  inArray,
+  gte,
+  lte,
   messages as messagesTable,
   or,
-  SessionRepository as SessionRepository2,
   select,
-  sql
+  sql,
+  visibleSessionReferenceAccessExists
 } from "@agor/core/db";
+var MAX_CROSS_SESSION_SEARCH_WINDOW_MS = 31 * 24 * 60 * 60 * 1e3;
 
 // src/mcp/tools/proxies.ts
-import { getBaseUrl, loadConfig, resolveProxies } from "@agor/core/config";
+import { getBaseUrl, loadConfig as loadConfig2, resolveProxies } from "@agor/core/config";
 
 // src/mcp/tools/repos.ts
 import { extractSlugFromUrl, isValidGitUrl, isValidSlug } from "@agor/core/config";
@@ -14929,7 +15164,7 @@ var agenticToolConfigSchema = external_exports.object({
   model_config: external_exports.object({
     mode: external_exports.enum(["alias", "exact"]).optional(),
     model: mcpOptionalString("model_config.model", "Model name override."),
-    effort: external_exports.enum(["low", "medium", "high", "max"]).optional(),
+    effort: external_exports.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
     advisorModel: mcpOptionalString(
       "model_config.advisorModel",
       "Claude Code advisor model override (e.g. 'opus', 'sonnet', 'fable')."
@@ -14945,7 +15180,7 @@ var agenticToolConfigSchema = external_exports.object({
 
 // src/mcp/tools/sessions.ts
 import {
-  BranchRepository as BranchRepository5,
+  BranchRepository as BranchRepository6,
   SessionRelationshipRepository,
   shortId as shortId5
 } from "@agor/core/db";
@@ -14968,6 +15203,7 @@ import {
 } from "@agor/core/types";
 init_branch_inspect();
 init_executor_read_impersonation();
+init_spawn_executor();
 var modelConfigObjectSchema = external_exports.object({
   mode: external_exports.enum(["alias", "exact"]).optional().describe("Model selection mode (default: 'alias')"),
   // .min(1): reject empty-string model explicitly so callers don't silently
@@ -14976,7 +15212,7 @@ var modelConfigObjectSchema = external_exports.object({
     "modelConfig.model",
     "Model identifier (e.g. 'claude-opus-4-6', 'claude-sonnet-4-6')"
   ),
-  effort: external_exports.enum(["low", "medium", "high", "max"]).optional().describe("Reasoning effort level (default: high)"),
+  effort: external_exports.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Reasoning effort level (default: high)"),
   advisorModel: mcpOptionalString(
     "modelConfig.advisorModel",
     "Claude Code advisor model override (e.g. 'opus', 'sonnet', 'fable', or a full model ID)."
@@ -14997,10 +15233,10 @@ var modelConfigInputSchema = external_exports.union([
 );
 
 // src/mcp/tools/users.ts
-import { ROLES as ROLES3 } from "@agor/core/types";
+import { ROLES as ROLES4 } from "@agor/core/types";
 
 // src/mcp/tools/widgets.ts
-import { MessageRole as MessageRole2 } from "@agor/core/types";
+import { getRequiredSecretFields as getRequiredSecretFields2, hasMinimumRole as hasMinimumRole5, MessageRole as MessageRole2, ROLES as ROLES6 } from "@agor/core/types";
 
 // src/utils/append-system-message.ts
 import { generateId as generateId2, SessionRepository as SessionRepository3 } from "@agor/core/db";
@@ -15010,9 +15246,20 @@ import { MessageRole } from "@agor/core/types";
 import { EXECUTING_TASK_STATUSES, isTaskExecuting } from "@agor/core/types";
 
 // src/widgets/env-vars/index.ts
-import { ENV_VAR_CONSTRAINTS, isEnvVarAllowed, validateEnvVar } from "@agor/core/config";
+import {
+  ENV_VAR_CONSTRAINTS,
+  isEnvVarAllowed,
+  validateEnvVar
+} from "@agor/core/config";
+import { SessionEnvSelectionRepository } from "@agor/core/db";
 import { BadRequest } from "@agor/core/feathers";
 var ENV_VAR_NAME_REGEX = ENV_VAR_CONSTRAINTS.NAME_PATTERN;
+var envVarFieldMetadataSchema = external_exports.object({
+  description: external_exports.string().max(200).optional(),
+  placeholder: external_exports.string().max(120).optional(),
+  format_hint: external_exports.string().max(80).optional(),
+  input_type: external_exports.enum(["password", "text", "textarea"]).default("password").optional()
+}).strict();
 var envVarsParamsSchema = external_exports.object({
   names: external_exports.array(external_exports.string().regex(ENV_VAR_NAME_REGEX)).min(1).max(10).refine((names) => new Set(names).size === names.length, {
     message: "Env var names must be unique"
@@ -15020,20 +15267,82 @@ var envVarsParamsSchema = external_exports.object({
   reason: external_exports.string().min(1).max(200).describe(
     "One sentence explaining why you need the value(s). Keep it tight \u2014 this renders in a small muted line under the input. NOT a place to restate what the widget does."
   ),
+  variable_metadata: external_exports.record(external_exports.string().regex(ENV_VAR_NAME_REGEX), envVarFieldMetadataSchema).optional().describe(
+    "Optional per-variable display metadata keyed by requested name. Allowed keys per variable: description, placeholder, format_hint, input_type (password|text|textarea). Do not include values, defaults, examples containing secrets, or anything secret-like."
+  ),
   auto_resume: external_exports.boolean().default(true).describe(
     "When true (default), a system-authored prompt is auto-queued back into the agent on submit/dismiss."
   )
+}).superRefine((params, ctx) => {
+  const requested = new Set(params.names);
+  for (const key of Object.keys(params.variable_metadata ?? {})) {
+    if (!requested.has(key)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["variable_metadata", key],
+        message: `Metadata key ${key} must match a requested env var name`
+      });
+    }
+  }
 });
 var envVarsSubmitSchema = external_exports.object({
   values: external_exports.record(
     external_exports.string().regex(ENV_VAR_NAME_REGEX),
     external_exports.string().min(1).max(ENV_VAR_CONSTRAINTS.MAX_VALUE_LENGTH)
-  ).refine((v) => Object.keys(v).length >= 1 && Object.keys(v).length <= 10, {
-    message: "Must submit between 1 and 10 env vars"
-  }),
+  ).default({}),
+  use_existing: external_exports.array(external_exports.string().regex(ENV_VAR_NAME_REGEX)).max(10).default([]).describe("Requested names whose already-saved global values should be used."),
   scope: external_exports.enum(["global", "session"])
+}).superRefine((submit, ctx) => {
+  const valueNames = Object.keys(submit.values);
+  const existingNames = submit.use_existing;
+  const total = valueNames.length + existingNames.length;
+  if (total < 1 || total > 10) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      message: "Must submit between 1 and 10 env vars"
+    });
+  }
+  const duplicates = existingNames.filter((name) => valueNames.includes(name));
+  for (const name of duplicates) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["use_existing"],
+      message: `Cannot both submit and use existing value for ${name}`
+    });
+  }
+  if (new Set(existingNames).size !== existingNames.length) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["use_existing"],
+      message: "use_existing names must be unique"
+    });
+  }
 });
 
+// src/widgets/gateway-token/index.ts
+import { Forbidden as Forbidden2 } from "@agor/core/feathers";
+import {
+  GATEWAY_SENSITIVE_CONFIG_FIELDS as GATEWAY_SENSITIVE_CONFIG_FIELDS2,
+  hasMinimumRole as hasMinimumRole4,
+  ROLES as ROLES5
+} from "@agor/core/types";
+var MAX_TOKEN_LENGTH = 8192;
+var gatewayTokenParamsSchema = external_exports.object({
+  gatewayChannelId: external_exports.string().min(1).describe("Gateway channel whose credentials are being set."),
+  channelType: external_exports.enum(["slack", "discord", "whatsapp", "telegram", "github", "teams"]).describe("Platform type of the channel; drives per-field placeholders."),
+  channelName: external_exports.string().min(1).max(200).describe("Human-readable channel name for the form heading and prompts."),
+  fields: external_exports.array(external_exports.enum(GATEWAY_SENSITIVE_CONFIG_FIELDS2)).min(1).max(GATEWAY_SENSITIVE_CONFIG_FIELDS2.length).refine((fields) => new Set(fields).size === fields.length, {
+    message: "Token field names must be unique"
+  }).describe("Secret config field names to collect (subset of the sensitive fields)."),
+  reason: external_exports.string().min(1).max(200).describe("One sentence explaining why the tokens are needed. Renders as a muted line.")
+}).strict();
+var gatewayTokenSubmitSchema = external_exports.object({
+  tokens: external_exports.partialRecord(
+    external_exports.enum(GATEWAY_SENSITIVE_CONFIG_FIELDS2),
+    external_exports.string().min(1).max(MAX_TOKEN_LENGTH)
+  ).describe("Map of sensitive field name \u2192 credential value.")
+}).strict();
+
 // src/mcp/server.ts
 var DEBUG_MCP_REQUESTS = process.env.AGOR_DEBUG_MCP_REQUESTS === "1" || process.env.DEBUG?.includes("mcp-requests");
 function textResult(data) {
@@ -15126,6 +15435,329 @@ async function listAttachedMcpServers(ctx, sessionId, opts = {}) {
   }
   return summaries;
 }
+var mcpNameSchema = external_exports.string({
+  error: 'name is required and must be a string. Example: { "name": "context7" }'
+}).regex(
+  /^[a-z][a-z0-9_-]{0,63}$/,
+  'name must start with a lowercase letter and contain only lowercase letters, digits, "_" or "-" (max 64 chars).'
+).describe('Stable internal ID, e.g. "context7", "github", "datadog". Cannot be changed later.');
+var stringMapSchema = external_exports.record(external_exports.string(), external_exports.string()).describe(
+  "JSON object of string keys/values. Values may use templates like {{ user.env.API_TOKEN }}."
+);
+var mcpAuthInputSchema = external_exports.strictObject({
+  type: external_exports.enum(["none", "bearer", "jwt", "oauth"]).describe(
+    "Authentication mode. OAuth tip: start with { type: 'oauth' } plus the MCP server URL; only add endpoint/client fields if discovery/DCR fails."
+  ),
+  token: mcpOptionalString(
+    "auth.token",
+    "Bearer token. Prefer {{ user.env.MCP_TOKEN }} templates; raw secrets will be stored redacted but are still visible in this MCP call transcript."
+  ),
+  api_url: mcpOptionalString("auth.api_url", "JWT auth API URL."),
+  api_token: mcpOptionalString(
+    "auth.api_token",
+    "JWT API token. Prefer {{ user.env.JWT_TOKEN }} templates."
+  ),
+  api_secret: mcpOptionalString(
+    "auth.api_secret",
+    "JWT API secret. Prefer {{ user.env.JWT_SECRET }} templates."
+  ),
+  oauth_authorization_url: mcpOptionalString(
+    "auth.oauth_authorization_url",
+    "Optional OAuth authorization endpoint override. Leave blank for discovery."
+  ),
+  oauth_token_url: mcpOptionalString(
+    "auth.oauth_token_url",
+    "Optional OAuth token endpoint override. Leave blank for discovery."
+  ),
+  oauth_client_id: mcpOptionalString(
+    "auth.oauth_client_id",
+    "Optional OAuth client ID for providers that require a pre-registered app. Leave blank for Dynamic Client Registration where supported."
+  ),
+  oauth_client_secret: mcpOptionalString(
+    "auth.oauth_client_secret",
+    "Optional OAuth client secret. Prefer {{ user.env.OAUTH_CLIENT_SECRET }} templates; raw secrets are not returned by this tool."
+  ),
+  oauth_scope: mcpOptionalString("auth.oauth_scope", "Optional OAuth scopes, space-separated."),
+  oauth_grant_type: external_exports.enum(["client_credentials", "authorization_code"]).optional().describe(
+    "OAuth grant type hint. Defaults to 'client_credentials' for legacy token testing; browser OAuth uses authorization code with PKCE."
+  ),
+  oauth_mode: external_exports.enum(["per_user", "shared"]).optional().describe("OAuth token ownership. Defaults to 'per_user' (recommended)."),
+  insecure: external_exports.boolean().optional().describe("Allow insecure auth behavior if supported.")
+}).superRefine((auth, issue2) => {
+  if (auth.type === "bearer" && !auth.token) {
+    issue2.addIssue({
+      code: "custom",
+      path: ["token"],
+      message: "auth.token is required when auth.type is 'bearer'."
+    });
+  }
+  const fieldsByType = {
+    none: [],
+    bearer: ["token"],
+    jwt: ["api_url", "api_token", "api_secret"],
+    oauth: [
+      "oauth_authorization_url",
+      "oauth_token_url",
+      "oauth_client_id",
+      "oauth_client_secret",
+      "oauth_scope",
+      "oauth_grant_type",
+      "oauth_mode",
+      "insecure"
+    ]
+  };
+  const allowed = /* @__PURE__ */ new Set(["type", ...fieldsByType[auth.type]]);
+  for (const key of Object.keys(auth)) {
+    if (!allowed.has(key)) {
+      issue2.addIssue({
+        code: "custom",
+        path: [key],
+        message: `auth.${key} does not apply when auth.type is '${auth.type}'.`
+      });
+    }
+  }
+  if (auth.type === "jwt") {
+    for (const field of ["api_url", "api_token", "api_secret"]) {
+      if (!auth[field]) {
+        issue2.addIssue({
+          code: "custom",
+          path: [field],
+          message: `auth.${field} is required when auth.type is 'jwt'.`
+        });
+      }
+    }
+  }
+}).describe(
+  "Auth config. Common OAuth path: { type: 'oauth' } plus url; leave OAuth URLs/client fields blank first so metadata discovery/DCR can do the work."
+);
+var toolPermissionsSchema = external_exports.record(external_exports.string(), external_exports.enum(["ask", "allow", "deny"])).describe("Optional per-tool permissions, e.g. { 'list_files': 'allow', 'write_file': 'ask' }.");
+var mcpServerCreateSchema = external_exports.strictObject({
+  name: mcpNameSchema,
+  displayName: mcpOptionalNonEmptyString(
+    "displayName",
+    'Human-friendly display name, e.g. "Context7 MCP".'
+  ),
+  description: mcpOptionalString("description", "Optional description."),
+  transport: external_exports.enum(["stdio", "http", "sse"]).optional().describe(
+    "Transport. Defaults to 'http' when url is provided, otherwise 'stdio'. Most remote OAuth MCP servers use 'http'."
+  ),
+  url: mcpOptionalString(
+    "url",
+    "Remote MCP server URL for http/sse transports. Supports templates like {{ user.env.MCP_URL }}."
+  ),
+  command: mcpOptionalString("command", 'Local command for stdio transport, e.g. "npx".'),
+  args: external_exports.array(external_exports.string()).optional().describe(
+    'Arguments for stdio command, e.g. ["-y", "@modelcontextprotocol/server-filesystem"].'
+  ),
+  headers: stringMapSchema.optional().describe(
+    "Custom HTTP headers for http/sse transports. Do not include Authorization; use auth instead. Prefer templates for secret values."
+  ),
+  env: stringMapSchema.optional().describe(
+    "Environment variables for the MCP process/config. Prefer {{ user.env.VAR }} templates for secrets."
+  ),
+  auth: mcpAuthInputSchema.optional(),
+  scope: external_exports.enum(["global", "session"]).optional().describe(
+    "Scope. Defaults to 'global' so it appears in agor_mcp_servers_list. 'session' is only for explicit session attachment workflows."
+  ),
+  enabled: external_exports.boolean().optional().describe("Whether the server is enabled. Defaults to true."),
+  attachToCurrentSession: external_exports.boolean().optional().describe(
+    `If true, also add a session-specific link after creating. Mostly useful for scope:"session" servers; global enabled servers are already in each session's effective MCP set.`
+  ),
+  attachToSessionId: mcpOptionalId(
+    "attachToSessionId",
+    "Session",
+    "Optional session ID (UUIDv7 or short ID) to attach after creating. Overrides attachToCurrentSession."
+  )
+}).superRefine((value, issue2) => validateMcpServerConfig(value, issue2, false));
+var mcpServerUpdateSchema = external_exports.strictObject({
+  mcpServerId: mcpRequiredId(
+    "mcpServerId",
+    "MCP server",
+    "MCP server ID to update (UUIDv7 or short ID)"
+  ),
+  displayName: mcpOptionalNonEmptyString("displayName", "New human-friendly display name."),
+  description: mcpOptionalString(
+    "description",
+    "New description. Pass an empty string to clear."
+  ),
+  transport: external_exports.enum(["stdio", "http", "sse"]).optional().describe("Transport to set."),
+  url: mcpOptionalString("url", "Remote MCP URL for http/sse transports."),
+  command: mcpOptionalString("command", "Local command for stdio transport."),
+  args: external_exports.array(external_exports.string()).optional().describe("Arguments for stdio command."),
+  headers: stringMapSchema.optional().describe(
+    "Replace custom HTTP headers. Redacted existing header values may be passed back unchanged by the UI; this tool should normally pass real template values or omit headers."
+  ),
+  env: stringMapSchema.optional().describe("Replace environment variables."),
+  auth: mcpAuthInputSchema.optional().describe(
+    "Replace auth config. Existing redacted secrets are preserved if their redacted placeholders are passed back; prefer omitting auth unless changing it. Use { type: 'none' } to clear auth."
+  ),
+  scope: external_exports.enum(["global", "session"]).optional().describe("Scope to set."),
+  enabled: external_exports.boolean().optional().describe("Enabled flag."),
+  toolPermissions: toolPermissionsSchema.optional()
+}).superRefine((value, issue2) => validateMcpServerConfig(value, issue2, true));
+function validateHeaders(headers, issue2) {
+  if (!headers) return;
+  for (const [key, value] of Object.entries(headers)) {
+    const name = key.trim();
+    if (!name) {
+      issue2.addIssue({
+        code: "custom",
+        path: ["headers", key],
+        message: "Header names cannot be empty."
+      });
+    } else if (!isValidMCPHeaderName(name)) {
+      issue2.addIssue({
+        code: "custom",
+        path: ["headers", key],
+        message: `Invalid HTTP header name: ${key}`
+      });
+    } else if (isReservedMCPCustomHeaderName(name)) {
+      issue2.addIssue({
+        code: "custom",
+        path: ["headers", key],
+        message: `Header ${name} is reserved; configure Authorization through auth instead.`
+      });
+    }
+    if (typeof value !== "string") {
+      issue2.addIssue({
+        code: "custom",
+        path: ["headers", key],
+        message: "Header values must be strings."
+      });
+    }
+  }
+}
+function validateMcpServerConfig(value, issue2, partial2) {
+  const transport = value.transport ?? (value.url ? "http" : "stdio");
+  validateHeaders(value.headers, issue2);
+  if (!partial2 || value.transport !== void 0 || value.url !== void 0 || value.command !== void 0) {
+    if (transport === "stdio") {
+      if (!partial2 && !value.command) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["command"],
+          message: "command is required for stdio transport."
+        });
+      }
+      if (value.url) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["url"],
+          message: "url only applies to http/sse transports, not stdio."
+        });
+      }
+      if (value.headers) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["headers"],
+          message: "headers only apply to http/sse transports, not stdio."
+        });
+      }
+      if (value.auth && value.auth.type !== "none") {
+        issue2.addIssue({
+          code: "custom",
+          path: ["auth", "type"],
+          message: "Authentication config only applies to http/sse transports."
+        });
+      }
+    } else if (!partial2 && !value.url) {
+      issue2.addIssue({
+        code: "custom",
+        path: ["url"],
+        message: `url is required for ${transport} transport.`
+      });
+    } else {
+      if (value.command) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["command"],
+          message: "command only applies to stdio transport, not http/sse."
+        });
+      }
+      if (value.args && value.args.length > 0) {
+        issue2.addIssue({
+          code: "custom",
+          path: ["args"],
+          message: "args only apply to stdio transport, not http/sse."
+        });
+      }
+    }
+  }
+}
+function assertUpdateCompatibleWithCurrent(current, args) {
+  const transport = args.transport ?? current.transport;
+  const url2 = args.url ?? current.url;
+  const command = args.command ?? current.command;
+  const errors = [];
+  if (transport === "stdio") {
+    if (!command) errors.push("command is required for stdio transport.");
+    if (args.url) errors.push("url only applies to http/sse transports, not stdio.");
+    if (args.headers && Object.keys(args.headers).length > 0) {
+      errors.push("headers only apply to http/sse transports, not stdio.");
+    }
+    if (args.auth && args.auth.type !== "none") {
+      errors.push("auth only applies to http/sse transports, not stdio.");
+    }
+  } else {
+    if (!url2) errors.push(`url is required for ${transport} transport.`);
+    if (args.command) errors.push("command only applies to stdio transport, not http/sse.");
+    if (args.args && args.args.length > 0) {
+      errors.push("args only apply to stdio transport, not http/sse.");
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(`Invalid MCP server update: ${errors.join(" ")}`);
+  }
+}
+function createOrUpdateNextSteps(server, attach) {
+  const authType = server.auth?.type || "none";
+  const steps = [];
+  if (authType === "oauth") {
+    steps.push(
+      `OAuth configured. If oauth_authenticated is false, authenticate in Settings > MCP Servers > ${server.display_name || server.name} > Test Authentication > Start OAuth Flow.`
+    );
+  }
+  if (attach?.ok) {
+    steps.push(
+      `Attached to session ${attach.sessionId}. Restart or re-prompt the agent if its MCP client does not hot-reload tools.`
+    );
+  } else if (attach?.error) {
+    steps.push(`Attach to session ${attach.sessionId} failed: ${attach.error}`);
+  } else if (server.scope === "global") {
+    steps.push(
+      "This enabled global MCP server is in every session\u2019s effective MCP set. Restart or re-prompt an existing agent if its MCP client does not hot-reload tools."
+    );
+  } else {
+    steps.push(
+      "This session-scoped MCP server must be linked to a session with agor_sessions_add_mcp_server (or set on session creation) before that session can use it."
+    );
+  }
+  return steps;
+}
+async function attachMcpServerToSession(ctx, sessionId, mcpServerId) {
+  return ctx.app.service("/sessions/:id/mcp-servers").create(
+    { mcpServerId },
+    {
+      ...ctx.baseServiceParams,
+      route: { id: sessionId }
+    }
+  );
+}
+async function removeMcpServerFromSession(ctx, sessionId, mcpServerId) {
+  return ctx.app.service("/sessions/:id/mcp-servers").remove(mcpServerId, {
+    ...ctx.baseServiceParams,
+    route: { id: sessionId }
+  });
+}
+async function resolveTargetSessionId(ctx, sessionId) {
+  const targetSessionId = sessionId ? await resolveSessionId(ctx, sessionId) : ctx.sessionId;
+  if (!targetSessionId) {
+    return {
+      error: "No current session context. Pass sessionId explicitly, or reconnect with X-Agor-Session-Id / a session-scoped MCP token."
+    };
+  }
+  return { sessionId: targetSessionId };
+}
 function registerMcpServerTools(server, ctx) {
   server.registerTool(
     "agor_mcp_servers_list",
@@ -15192,6 +15824,249 @@ function registerMcpServerTools(server, ctx) {
       });
     }
   );
+  server.registerTool(
+    "agor_mcp_servers_create",
+    {
+      description: 'Register a new MCP server definition. Permissions are service-enforced: only admins can create MCP configs. Scope matters: enabled `global` servers are automatically in each session\'s effective MCP set; `session` scoped servers must be linked with `agor_sessions_add_mcp_server` (or `attachToCurrentSession` / `attachToSessionId`). Start simple for remote OAuth: `name` + `url` + `auth:{type:"oauth"}`; add endpoint/client fields only if discovery/DCR fails. For stdio use `transport:"stdio"` + `command` (+ `args`). Use `auth`, not Authorization headers. Prefer `{{ user.env.SECRET_NAME }}` templates; raw secrets are visible in the MCP transcript though never returned.',
+      annotations: { destructiveHint: false, idempotentHint: false },
+      inputSchema: mcpServerCreateSchema
+    },
+    async (args) => {
+      const transport = args.transport ?? (args.url ? "http" : "stdio");
+      const wantsAttach = args.attachToSessionId !== void 0 || args.attachToCurrentSession;
+      const attachTargetResult = wantsAttach ? await resolveTargetSessionId(ctx, args.attachToSessionId) : void 0;
+      if (attachTargetResult && "error" in attachTargetResult) {
+        return { ...textResult({ error: attachTargetResult.error }), isError: true };
+      }
+      const attachTarget = attachTargetResult?.sessionId;
+      const createData = {
+        name: args.name,
+        display_name: args.displayName,
+        description: args.description,
+        transport,
+        command: transport === "stdio" ? args.command : void 0,
+        args: transport === "stdio" ? args.args : void 0,
+        url: transport === "stdio" ? void 0 : args.url,
+        headers: transport === "stdio" ? void 0 : args.headers,
+        env: args.env,
+        auth: transport === "stdio" || !args.auth || args.auth.type === "none" ? void 0 : args.auth,
+        scope: args.scope ?? "global",
+        source: "user",
+        enabled: args.enabled ?? true
+      };
+      const created = await ctx.app.service("mcp-servers").create(createData, ctx.baseServiceParams);
+      let attachResult;
+      if (attachTarget) {
+        try {
+          await attachMcpServerToSession(ctx, attachTarget, created.mcp_server_id);
+          attachResult = { sessionId: attachTarget, ok: true };
+        } catch (error51) {
+          attachResult = {
+            sessionId: attachTarget,
+            ok: false,
+            error: error51 instanceof Error ? error51.message : String(error51)
+          };
+        }
+      }
+      const summary = await summarizeMcpServer(ctx, created);
+      return textResult({
+        mcp_server: summary,
+        attached: attachResult?.ok ? { session_id: attachResult.sessionId, mcp_server_id: created.mcp_server_id } : void 0,
+        attach_error: attachResult && !attachResult.ok ? attachResult.error : void 0,
+        next_steps: createOrUpdateNextSteps(created, attachResult)
+      });
+    }
+  );
+  server.registerTool(
+    "agor_mcp_servers_update",
+    {
+      description: 'Update an existing MCP server definition. Permissions are service-enforced: only admins can update MCP configs. Updating config does not create a session-specific link: enabled `global` servers are already effective for all sessions, while `session` scoped servers need `agor_sessions_add_mcp_server`. Provide only fields to change. Validation rejects incompatible combinations (e.g. stdio+url/auth/headers, remote+command/args, wrong auth fields). OAuth tip: keep only `auth:{type:"oauth"}` unless discovery fails or a provider requires endpoint/client overrides. Use `auth:{type:"none"}` to clear auth.',
+      annotations: { destructiveHint: false, idempotentHint: false },
+      inputSchema: mcpServerUpdateSchema
+    },
+    async (args) => {
+      const mcpServerId = await resolveMcpServerId(ctx, args.mcpServerId);
+      const current = await ctx.app.service("mcp-servers").get(mcpServerId, ctx.baseServiceParams);
+      assertUpdateCompatibleWithCurrent(current, args);
+      const updates = {};
+      if (args.displayName !== void 0) updates.display_name = args.displayName;
+      if (args.description !== void 0) updates.description = args.description;
+      if (args.transport !== void 0) updates.transport = args.transport;
+      if (args.command !== void 0) updates.command = args.command;
+      if (args.args !== void 0) updates.args = args.args;
+      if (args.url !== void 0) updates.url = args.url;
+      if (args.headers !== void 0) updates.headers = args.headers;
+      if (args.env !== void 0) updates.env = args.env;
+      if (args.auth !== void 0) {
+        updates.auth = args.auth.type === "none" ? { type: "none" } : args.auth;
+      }
+      if (args.scope !== void 0) updates.scope = args.scope;
+      if (args.enabled !== void 0) updates.enabled = args.enabled;
+      if (args.toolPermissions !== void 0) updates.tool_permissions = args.toolPermissions;
+      if (args.transport === "stdio") {
+        updates.url = void 0;
+        updates.headers = void 0;
+        updates.auth = void 0;
+      } else if (args.transport === "http" || args.transport === "sse") {
+        updates.command = void 0;
+        updates.args = void 0;
+      }
+      const updated = await ctx.app.service("mcp-servers").patch(mcpServerId, updates, ctx.baseServiceParams);
+      return textResult({
+        mcp_server: await summarizeMcpServer(ctx, updated),
+        next_steps: createOrUpdateNextSteps(updated)
+      });
+    }
+  );
+  server.registerTool(
+    "agor_sessions_add_mcp_server",
+    {
+      description: "Attach a registered MCP server to a session. Defaults to current session when `sessionId` is omitted. Permissions are service-enforced via the same session-scoped route as the UI: caller must be allowed to edit that session config. Verify with `agor_sessions_get_current`/`agor_sessions_get`; the agent may need a restart/re-prompt before its MCP client sees new tools.",
+      annotations: { destructiveHint: false, idempotentHint: true },
+      inputSchema: external_exports.strictObject({
+        mcpServerId: mcpRequiredId(
+          "mcpServerId",
+          "MCP server",
+          "MCP server ID to attach (UUIDv7 or short ID)"
+        ),
+        sessionId: mcpOptionalId(
+          "sessionId",
+          "Session",
+          "Target session ID (UUIDv7 or short ID). Omit to attach to the current session."
+        )
+      })
+    },
+    async (args) => {
+      const target = await resolveTargetSessionId(ctx, args.sessionId);
+      if ("error" in target) {
+        return {
+          ...textResult({
+            error: target.error
+          }),
+          isError: true
+        };
+      }
+      const sessionId = target.sessionId;
+      const mcpServerId = await resolveMcpServerId(ctx, args.mcpServerId);
+      const relationship = await attachMcpServerToSession(ctx, sessionId, mcpServerId);
+      const mcpServer = await ctx.app.service("mcp-servers").get(mcpServerId, ctx.baseServiceParams);
+      return textResult({
+        relationship,
+        mcp_server: await summarizeMcpServer(ctx, mcpServer),
+        next_steps: createOrUpdateNextSteps(mcpServer, { sessionId, ok: true })
+      });
+    }
+  );
+  server.registerTool(
+    "agor_sessions_remove_mcp_server",
+    {
+      description: "Remove a session-specific MCP server link from a session. Defaults to current session when `sessionId` is omitted. Permissions are service-enforced by the same session-scoped route as the UI. This only removes the session link; it does not delete the registered MCP server. Note: enabled global MCP servers remain effective for all sessions and cannot be removed from just one session with this link-removal tool.",
+      annotations: { destructiveHint: true, idempotentHint: true },
+      inputSchema: external_exports.strictObject({
+        mcpServerId: mcpRequiredId(
+          "mcpServerId",
+          "MCP server",
+          "MCP server ID to remove from the session (UUIDv7 or short ID)"
+        ),
+        sessionId: mcpOptionalId(
+          "sessionId",
+          "Session",
+          "Target session ID (UUIDv7 or short ID). Omit to use the current session."
+        )
+      })
+    },
+    async (args) => {
+      const target = await resolveTargetSessionId(ctx, args.sessionId);
+      if ("error" in target) {
+        return { ...textResult({ error: target.error }), isError: true };
+      }
+      const mcpServerId = await resolveMcpServerId(ctx, args.mcpServerId);
+      const relationship = await removeMcpServerFromSession(ctx, target.sessionId, mcpServerId);
+      return textResult({
+        relationship,
+        removed: { session_id: target.sessionId, mcp_server_id: mcpServerId },
+        next_steps: [
+          "Verify with agor_sessions_get_current/agor_sessions_get. Restart or re-prompt an existing agent if its MCP client does not hot-reload tool removals."
+        ]
+      });
+    }
+  );
+  server.registerTool(
+    "agor_sessions_set_mcp_servers",
+    {
+      description: "Replace the session-specific MCP links for a session by diffing through the same add/remove route the UI uses. Defaults to current session when `sessionId` is omitted. Permissions are service-enforced per add/remove. This manages session links only; enabled global MCP servers are still effective for every session even if omitted here.",
+      annotations: { destructiveHint: true, idempotentHint: true },
+      inputSchema: external_exports.strictObject({
+        mcpServerIds: external_exports.array(mcpRequiredId("mcpServerIds[]", "MCP server", "MCP server ID")).describe(
+          "Exact desired set of session-specific MCP server IDs. Pass [] to remove all session-specific links."
+        ),
+        sessionId: mcpOptionalId(
+          "sessionId",
+          "Session",
+          "Target session ID (UUIDv7 or short ID). Omit to use the current session."
+        )
+      })
+    },
+    async (args) => {
+      const target = await resolveTargetSessionId(ctx, args.sessionId);
+      if ("error" in target) {
+        return { ...textResult({ error: target.error }), isError: true };
+      }
+      const desired = [
+        ...new Set(await Promise.all(args.mcpServerIds.map((id) => resolveMcpServerId(ctx, id))))
+      ];
+      const currentResult = await ctx.app.service("/sessions/:id/mcp-servers").find({
+        ...ctx.baseServiceParams,
+        route: { id: target.sessionId }
+      });
+      const currentServers = Array.isArray(currentResult) ? currentResult : currentResult.data;
+      const current = currentServers.map((s) => s.mcp_server_id);
+      const currentSet = new Set(current);
+      const desiredSet = new Set(desired);
+      const toAdd = desired.filter((id) => !currentSet.has(id));
+      const toRemove = current.filter((id) => !desiredSet.has(id));
+      const failures = [];
+      for (const mcpServerId of toRemove) {
+        try {
+          await removeMcpServerFromSession(ctx, target.sessionId, mcpServerId);
+        } catch (error51) {
+          failures.push({
+            mcp_server_id: mcpServerId,
+            action: "remove",
+            reason: error51 instanceof Error ? error51.message : String(error51)
+          });
+        }
+      }
+      for (const mcpServerId of toAdd) {
+        try {
+          await attachMcpServerToSession(ctx, target.sessionId, mcpServerId);
+        } catch (error51) {
+          failures.push({
+            mcp_server_id: mcpServerId,
+            action: "add",
+            reason: error51 instanceof Error ? error51.message : String(error51)
+          });
+        }
+      }
+      const payload = {
+        session_id: target.sessionId,
+        desired_mcp_server_ids: desired,
+        added_mcp_server_ids: toAdd.filter(
+          (id) => !failures.some((f) => f.action === "add" && f.mcp_server_id === id)
+        ),
+        removed_mcp_server_ids: toRemove.filter(
+          (id) => !failures.some((f) => f.action === "remove" && f.mcp_server_id === id)
+        ),
+        unchanged_mcp_server_ids: desired.filter((id) => currentSet.has(id)),
+        failures: failures.length > 0 ? failures : void 0,
+        next_steps: [
+          "Verify with agor_sessions_get_current/agor_sessions_get. Enabled global MCP servers remain effective even if not listed here.",
+          "Restart or re-prompt an existing agent if its MCP client does not hot-reload MCP link changes."
+        ]
+      };
+      return failures.length > 0 ? { ...textResult(payload), isError: true } : textResult(payload);
+    }
+  );
 }
 export {
   listAttachedMcpServers,