@plurnk/plurnk-mcp 1.7.0 → 1.8.0

package/dist/Module.js

@@ -1,12 +1,11 @@
 import { Problems, Validator, } from "@plurnk/plurnk-contracts";
-import { SdkError, SdkErrorCode, } from "@modelcontextprotocol/client";
-import ServerConnection, { AuthorizationRequiredError } from "./client.js";
-import { serviceDefinitions } from "./config.js";
-import McpExecutor, { runtimeDecl } from "./McpExecutor.js";
+import ServerConnection, { AuthorizationRequiredError, isClientCredentialsRejection, } from "./client.js";
+import { expandedServerNames, overlayServerDefinitions, serviceDefinitions, serviceEnabledNames, summaryOverrides, } from "./config.js";
+import McpExecutor, { runtimeDecl, serverSummary } from "./McpExecutor.js";
 import McpResources from "./McpResources.js";
-import { MCP_PROTOCOL_VERSION } from "./protocol.js";
 const OWNER = "@plurnk/plurnk-mcp";
 const STATE_VERSION = 1;
+const attachmentConnection = (attachment) => attachment.kind === "unavailable" ? undefined : attachment.connection;
 class ModuleActionError extends Error {
     problem;
     constructor(problem, cause) {
@@ -21,36 +20,20 @@ const actionError = (code, status, detail, extensions = {}, cause) => new Module
     ...extensions,
 }), cause);
 const errorsOf = (error) => error instanceof AggregateError ? [...error.errors] : [error];
-const errorTreeSome = (error, predicate, seen = new Set()) => {
-    if ((typeof error !== "object" && typeof error !== "function") || error === null) {
-        return predicate(error);
-    }
-    if (seen.has(error))
-        return false;
-    seen.add(error);
-    if (predicate(error))
-        return true;
-    if (error instanceof AggregateError) {
-        return [...error.errors].some((candidate) => errorTreeSome(candidate, predicate, seen));
-    }
-    return error instanceof Error && error.cause !== undefined
-        ? errorTreeSome(error.cause, predicate, seen)
-        : false;
-};
-const lacksRequiredProtocolRevision = (error) => errorTreeSome(error, (candidate) => SdkError.isInstance(candidate)
-    && candidate.code === SdkErrorCode.EraNegotiationFailed
-    && candidate.message.includes("the server did not offer pinned protocol version")
-    && candidate.message.includes("via server/discover"));
 const preparationError = (definition, cause, closeCause) => {
     const completeCause = closeCause === undefined
         ? cause
         : new AggregateError([cause, closeCause], `MCP server '${definition.name}' preparation and cleanup failed.`);
-    if (lacksRequiredProtocolRevision(cause)) {
-        return actionError("protocol-revision-unsupported", 502, `MCP server '${definition.name}' did not offer required revision ${MCP_PROTOCOL_VERSION} through server/discover; upgrade or replace the legacy endpoint.`, {
+    // {§oauth-client-credentials} — a rejected grant is an authorization fact,
+    // never a generic unavailability.
+    if (definition.authorization?.type === "client-credentials" && isClientCredentialsRejection(cause)) {
+        return actionError("oauth-client-credentials-failed", 502, `MCP server '${definition.name}' rejected the client-credentials grant; check the configured client credentials and issuer.`, {
             server: definition.name,
             transport: definition.transport,
-            requiredRevision: MCP_PROTOCOL_VERSION,
-            requiredMethod: "server/discover",
+            clientId: definition.authorization.clientId,
+            ...(definition.authorization.issuer === undefined
+                ? {}
+                : { issuer: definition.authorization.issuer }),
             retryable: false,
         }, completeCause);
     }
@@ -94,26 +77,30 @@ const parseState = (source) => {
     const parsed = {};
     for (const [name, raw] of Object.entries(servers).toSorted(([left], [right]) => left.localeCompare(right))) {
         const value = objectOf(raw);
-        if (value === null || (value.kind !== "attached" && value.kind !== "detached")) {
+        if (value === null || (value.kind !== "service" && value.kind !== "workspace")) {
             throw new Error(`MCP workspace server '${name}' has an invalid state.`);
         }
-        if (value.kind === "detached") {
-            assertExactKeys(value, ["kind"], `MCP workspace server '${name}'`);
-            parsed[name] = { kind: "detached" };
+        if (typeof value.enabled !== "boolean") {
+            throw new Error(`MCP workspace server '${name}' must declare boolean enabledness.`);
+        }
+        if (value.kind === "service") {
+            assertExactKeys(value, ["kind", "enabled"], `MCP workspace server '${name}'`);
+            parsed[name] = { kind: "service", enabled: value.enabled };
             continue;
         }
-        assertExactKeys(value, ["kind", "definition"], `MCP workspace server '${name}'`);
+        assertExactKeys(value, ["kind", "definition", "enabled"], `MCP workspace server '${name}'`);
         const definition = structuredClone(Validator.assertMcpServerDefinition(value.definition));
         if (definition.name !== name) {
             throw new Error(`MCP workspace server key '${name}' does not match definition '${definition.name}'.`);
         }
-        parsed[name] = { kind: "attached", definition };
+        parsed[name] = { kind: "workspace", definition, enabled: value.enabled };
     }
     return { version: STATE_VERSION, servers: parsed };
 };
 const persistedState = (state) => Object.keys(state.servers).length === 0 ? null : state;
 const cloneState = (state) => parseState(structuredClone(state));
 const sameDefinition = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameServerState = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const requiredString = (params, field) => {
     const value = params[field];
     if (typeof value !== "string" || value.length === 0) {
@@ -121,6 +108,12 @@ const requiredString = (params, field) => {
     }
     return value;
 };
+const assertActionKeys = (params, allowed) => {
+    const extras = Object.keys(params).filter((key) => !allowed.includes(key));
+    if (extras.length === 0)
+        return;
+    throw actionError("parameters-invalid", 400, `MCP action contains unsupported parameter(s): ${extras.join(", ")}.`, { fields: extras, retryable: false });
+};
 const workspaceIdOf = (context) => {
     if (context.scope !== "workspace") {
         throw actionError("workspace-context-required", 500, "MCP action received no workspace context.");
@@ -138,8 +131,13 @@ const statusOf = (error) => {
 };
 export default class Module {
     #env;
+    #summaries;
+    #expanded;
     #defaults;
+    #defaultEnabled;
     #workspaces = new Map();
+    // {§oauth-lifetime} — pending candidates are process-memory per
+    // (workspace, alias); a restart loses them by design.
     #pending = new Map();
     #locks = new Map();
     #refreshTimers = new Map();
@@ -151,6 +149,9 @@ export default class Module {
     constructor(environ) {
         this.#env = environ;
         this.#defaults = new Map(serviceDefinitions(environ).map((definition) => [definition.name, definition]));
+        this.#defaultEnabled = new Set(serviceEnabledNames(environ));
+        this.#summaries = summaryOverrides(environ);
+        this.#expanded = new Set(expandedServerNames(environ));
     }
     async setup(seam) {
         this.#seam = seam;
@@ -159,15 +160,19 @@ export default class Module {
                 const state = parseState(await seam.readWorkspaceModuleState(workspaceId, OWNER));
                 await this.#applyState(workspaceId, state, {
                     authorizationDisposition: "publish-required",
+                    preparationFailureDisposition: "publish-unavailable",
                 });
             }),
         });
         const action = (name, handler) => seam.registerModuleAction({ name, scope: "workspace", handler });
-        action("workspace.mcp.list", async (_params, context) => this.#list(workspaceIdOf(context)));
-        action("workspace.mcp.attach", async (params, context) => this.#change("attach", workspaceIdOf(context), params));
-        action("workspace.mcp.replace", async (params, context) => this.#change("replace", workspaceIdOf(context), params));
-        action("workspace.mcp.detach", async (params, context) => this.#detach(workspaceIdOf(context), params));
-        action("workspace.mcp.reconnect", async (params, context) => this.#reconnect(workspaceIdOf(context), params));
+        action("workspace.mcp.list", async (params, context) => {
+            assertActionKeys(params, ["overlay"]);
+            return this.#list(workspaceIdOf(context), params.overlay);
+        });
+        action("workspace.mcp.add", async (params, context) => this.#add(workspaceIdOf(context), params));
+        action("workspace.mcp.enable", async (params, context) => this.#setEnabled(workspaceIdOf(context), params, true));
+        action("workspace.mcp.disable", async (params, context) => this.#setEnabled(workspaceIdOf(context), params, false));
+        action("workspace.mcp.remove", async (params, context) => this.#remove(workspaceIdOf(context), params));
         action("workspace.mcp.oauth.complete", async (params, context) => this.#completeOAuth(workspaceIdOf(context), params));
         action("workspace.mcp.complete", async (params, context) => this.#complete(workspaceIdOf(context), params));
     }
@@ -190,21 +195,34 @@ export default class Module {
                 this.#locks.delete(workspaceId);
         }
     }
-    #effective(state) {
-        const effective = new Map([...this.#defaults].map(([name, definition]) => [
+    #available(state) {
+        const available = new Map([...this.#defaults].map(([name, definition]) => [
             name,
-            { definition: structuredClone(definition), source: "service" },
+            {
+                definition: structuredClone(definition),
+                source: "service",
+                enabled: this.#defaultEnabled.has(name),
+            },
         ]));
         for (const [name, value] of Object.entries(state.servers)) {
-            if (value.kind === "detached")
-                effective.delete(name);
-            else
-                effective.set(name, {
-                    definition: structuredClone(value.definition),
-                    source: "workspace",
-                });
+            if (value.kind === "service") {
+                const configured = available.get(name);
+                if (configured !== undefined)
+                    available.set(name, { ...configured, enabled: value.enabled });
+                continue;
+            }
+            available.set(name, {
+                definition: structuredClone(value.definition),
+                source: "workspace",
+                enabled: value.enabled,
+            });
         }
-        return new Map([...effective].toSorted(([left], [right]) => left.localeCompare(right)));
+        return new Map([...available].toSorted(([left], [right]) => left.localeCompare(right)));
+    }
+    #enabled(state) {
+        return new Map([...this.#available(state)]
+            .filter(([, value]) => value.enabled)
+            .map(([name, { definition, source }]) => [name, { definition, source }]));
     }
     async #prepareAttachment(workspaceId, effective, connection) {
         const definition = effective.definition;
@@ -220,7 +238,7 @@ export default class Module {
                 console.error(`MCP server '${definition.name}' infrastructure failure:`, error);
             },
         });
-        const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, { tools: definition.tools ?? null, read: definition.read ?? [] });
+        const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, { tools: definition.tools ?? null, read: definition.read ?? [] }, this.#summaries.tools);
         try {
             const availability = await executor.requireAvailable();
             return {
@@ -230,7 +248,7 @@ export default class Module {
                 executor,
                 runtime: {
                     namespaceOwner: OWNER,
-                    decl: runtimeDecl(definition.name),
+                    decl: runtimeDecl(definition.name, serverSummary(definition.name, executor.catalog, this.#summaries.servers.get(definition.name)), this.#expanded.has(definition.name)),
                     executor,
                     availability,
                     scheme: new McpResources(definition.name, candidate, executor.catalog),
@@ -261,14 +279,14 @@ export default class Module {
         if (seam === undefined)
             throw new Error("MCP module is not set up.");
         const current = this.#workspaces.get(workspaceId);
-        const effective = this.#effective(state);
+        const effective = this.#enabled(state);
         const force = options.force ?? new Set();
         for (const [name, attachment] of current?.attachments ?? []) {
             const next = effective.get(name);
             if (next === undefined
                 || force.has(name)
                 || !sameDefinition(attachment.definition, next.definition))
-                attachment.connection.assertReplaceable();
+                attachmentConnection(attachment)?.assertReplaceable();
         }
         const next = new Map();
         const fresh = [];
@@ -282,9 +300,26 @@ export default class Module {
                     continue;
                 }
                 const supplied = options.prepared?.get(name);
-                const attachment = supplied ?? await this.#prepareAttachment(workspaceId, definition);
+                let attachment;
+                try {
+                    attachment = supplied ?? await this.#prepareAttachment(workspaceId, definition);
+                }
+                catch (cause) {
+                    if (options.preparationFailureDisposition === "reject")
+                        throw cause;
+                    const failure = cause instanceof ModuleActionError
+                        ? cause
+                        : preparationError(definition.definition, cause);
+                    attachment = {
+                        kind: "unavailable",
+                        ...definition,
+                        problem: structuredClone(failure.problem),
+                    };
+                    console.error(`MCP server '${name}' unavailable during workspace hydration: ${failure.problem.detail}`, failure.cause ?? failure);
+                }
                 next.set(name, attachment);
-                fresh.push(attachment);
+                if (attachment.kind !== "unavailable")
+                    fresh.push(attachment);
             }
         }
         catch (cause) {
@@ -319,9 +354,9 @@ export default class Module {
             throw cause;
         }
         this.#workspaces.set(workspaceId, { state: cloneState(state), attachments: next });
-        const retained = new Set([...next.values()].map(({ connection }) => connection));
+        const retained = new Set([...next.values()].flatMap((attachment) => attachmentConnection(attachment) ?? []));
         const obsolete = [...current?.attachments.values() ?? []]
-            .map(({ connection }) => connection)
+            .flatMap((attachment) => attachmentConnection(attachment) ?? [])
             .filter((connection) => !retained.has(connection));
         if (obsolete.length > 0) {
             try {
@@ -336,8 +371,10 @@ export default class Module {
                 if (attachment.kind !== "authorization-required")
                     continue;
                 await this.#setPending(workspaceId, name, {
-                    operation: "reconnect",
+                    operation: "enable",
+                    expectedState: structuredClone(state.servers[name] ?? null),
                     expectedDefinition: structuredClone(attachment.definition),
+                    expectedEnabled: true,
                     definition: {
                         definition: structuredClone(attachment.definition),
                         source: attachment.source,
@@ -377,17 +414,31 @@ export default class Module {
         }
         return snapshot;
     }
-    #summary(name, attachment) {
-        const definition = attachment.definition;
+    #summary(alias, available, attachment) {
+        const definition = available.definition;
         const base = {
-            name,
-            source: attachment.source,
+            alias,
+            source: available.source,
             transport: definition.transport,
-            state: attachment.kind === "active" ? "connected" : "authorization-required",
+            target: definition.transport === "http" ? definition.url : definition.command,
+            enabled: available.enabled,
+            state: available.enabled
+                ? attachment?.kind === "active"
+                    ? "connected"
+                    : attachment?.kind === "authorization-required"
+                        ? "authorization-required"
+                        : "unavailable"
+                : "disabled",
             enabledTools: definition.tools ?? null,
             read: definition.read ?? [],
         };
-        if (attachment.kind !== "active")
+        if (attachment?.kind === "authorization-required") {
+            return { ...base, authorization: { url: attachment.authorizationUrl } };
+        }
+        if (attachment?.kind === "unavailable") {
+            return { ...base, problem: structuredClone(attachment.problem) };
+        }
+        if (attachment?.kind !== "active")
             return base;
         const catalog = attachment.executor.catalog;
         return {
@@ -401,48 +452,86 @@ export default class Module {
             prompts: catalog.prompts.length,
         };
     }
-    #list(workspaceId) {
+    #overlayDefinitions(state, value) {
+        if (value === undefined)
+            return new Map();
+        try {
+            const bases = new Map([...this.#available(state)]
+                .map(([alias, { definition }]) => [alias, definition]));
+            return overlayServerDefinitions(structuredClone(value), bases);
+        }
+        catch (cause) {
+            throw actionError("configuration-invalid", 400, "Client MCP configuration is invalid.", { retryable: false }, cause);
+        }
+    }
+    #list(workspaceId, overlay) {
         const snapshot = this.#snapshot(workspaceId);
+        const available = this.#available(snapshot.state);
+        const configured = this.#overlayDefinitions(snapshot.state, overlay);
+        const summaries = new Map([...available].map(([alias, definition]) => [
+            alias,
+            this.#summary(alias, definition, snapshot.attachments.get(alias)),
+        ]));
+        for (const [alias, definition] of configured) {
+            if (available.has(alias))
+                continue;
+            summaries.set(alias, this.#summary(alias, {
+                definition,
+                source: "client",
+                enabled: false,
+            }));
+        }
         return {
-            servers: [...snapshot.attachments]
+            servers: [...summaries]
                 .toSorted(([left], [right]) => left.localeCompare(right))
-                .map(([name, attachment]) => this.#summary(name, attachment)),
+                .map(([, summary]) => summary),
         };
     }
     #definition(params) {
+        assertActionKeys(params, ["alias", "target", "options"]);
+        const alias = requiredString(params, "alias");
+        const target = requiredString(params, "target");
         try {
-            return structuredClone(Validator.assertMcpServerDefinition(params.server));
+            const options = structuredClone(Validator.assertMcpServerOptions((params.options ?? {})));
+            const definition = /^https?:\/\//u.test(target)
+                ? { name: alias, transport: "http", url: target, ...options }
+                : {
+                    name: alias,
+                    transport: "stdio",
+                    command: target,
+                    ...options,
+                    args: options.args ?? [],
+                };
+            return structuredClone(Validator.assertMcpServerDefinition(definition));
         }
         catch (cause) {
-            throw actionError("definition-invalid", 400, "The MCP server definition is invalid.", { field: "server", retryable: false }, cause);
+            throw actionError("definition-invalid", 400, `MCP server '${alias}' has an invalid target or options.`, { alias, retryable: false }, cause);
         }
     }
-    async #change(operation, workspaceId, params) {
+    async #add(workspaceId, params) {
         return this.#serialize(workspaceId, async () => {
             const definition = this.#definition(params);
+            const alias = definition.name;
             const snapshot = this.#snapshot(workspaceId);
-            const effective = this.#effective(snapshot.state);
-            const exists = effective.has(definition.name);
-            if (operation === "attach" ? exists : !exists) {
-                throw actionError(operation === "attach" ? "server-exists" : "server-not-found", operation === "attach" ? 409 : 404, operation === "attach"
-                    ? `MCP server '${definition.name}' is already attached to this workspace.`
-                    : `MCP server '${definition.name}' is not attached to this workspace.`, { workspaceId, name: definition.name, retryable: false });
+            if (this.#available(snapshot.state).has(alias)) {
+                throw actionError("server-exists", 409, `MCP server alias '${alias}' is already available in this workspace.`, { workspaceId, alias, retryable: false });
             }
             const state = cloneState(snapshot.state);
-            state.servers[definition.name] = {
-                kind: "attached",
+            state.servers[alias] = {
+                kind: "workspace",
                 definition,
+                enabled: true,
             };
             const result = await this.#applyState(workspaceId, state, {
-                force: new Set([definition.name]),
                 authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
             });
             if (result.authorization !== undefined) {
-                await this.#setPending(workspaceId, definition.name, {
-                    operation,
-                    expectedDefinition: exists
-                        ? structuredClone(effective.get(definition.name)?.definition ?? null)
-                        : null,
+                await this.#setPending(workspaceId, alias, {
+                    operation: "add",
+                    expectedState: structuredClone(snapshot.state.servers[alias] ?? null),
+                    expectedDefinition: null,
+                    expectedEnabled: false,
                     definition: { definition, source: "workspace" },
                     connection: result.authorization.connection,
                     authorizationUrl: result.authorization.authorizationUrl,
@@ -452,52 +541,118 @@ export default class Module {
                     authorization: { url: result.authorization.authorizationUrl },
                 };
             }
-            const attached = this.#snapshot(workspaceId).attachments.get(definition.name);
-            if (attached === undefined)
+            const committed = this.#snapshot(workspaceId);
+            const attached = committed.attachments.get(alias);
+            if (attached === undefined || attached.kind === "unavailable") {
                 throw new Error("Committed MCP attachment is absent.");
-            await this.#clearPending(workspaceId, definition.name, attached.connection);
-            return { status: operation === "attach" ? 201 : 200, server: this.#summary(definition.name, attached) };
-        });
-    }
-    async #detach(workspaceId, params) {
-        return this.#serialize(workspaceId, async () => {
-            const name = requiredString(params, "name");
-            const snapshot = this.#snapshot(workspaceId);
-            if (!this.#effective(snapshot.state).has(name)) {
-                throw actionError("server-not-found", 404, `MCP server '${name}' is not attached to this workspace.`, { workspaceId, name, retryable: false });
             }
-            const state = cloneState(snapshot.state);
-            if (this.#defaults.has(name)) {
-                state.servers[name] = { kind: "detached" };
-            }
-            else {
-                delete state.servers[name];
-            }
-            await this.#applyState(workspaceId, state, {
-                force: new Set([name]),
-                authorizationDisposition: "defer-mutation",
-            });
-            await this.#clearPending(workspaceId, name);
-            return { status: 200, name, detached: true };
+            await this.#clearPending(workspaceId, alias, attached.connection);
+            const available = this.#available(committed.state).get(alias);
+            if (available === undefined)
+                throw new Error("Committed MCP definition is absent.");
+            return { status: 201, server: this.#summary(alias, available, attached) };
         });
     }
-    async #reconnect(workspaceId, params) {
+    #stateWithEnabled(state, alias, available, enabled) {
+        const next = cloneState(state);
+        if (available.source === "service") {
+            next.servers[alias] = { kind: "service", enabled };
+            return next;
+        }
+        const current = next.servers[alias];
+        if (current?.kind !== "workspace") {
+            throw new Error(`Workspace MCP server '${alias}' has no owned definition.`);
+        }
+        next.servers[alias] = { ...current, enabled };
+        return next;
+    }
+    #stateWithDefinition(state, alias, definition, enabled) {
+        const next = cloneState(state);
+        next.servers[alias] = this.#definitionSource(alias, definition) === "service"
+            ? { kind: "service", enabled }
+            : {
+                kind: "workspace",
+                definition: structuredClone(definition),
+                enabled,
+            };
+        return next;
+    }
+    #definitionSource(alias, definition) {
+        const service = this.#defaults.get(alias);
+        return service !== undefined && sameDefinition(service, definition)
+            ? "service"
+            : "workspace";
+    }
+    #definitionWithOptions(definition, value) {
+        if (value === undefined)
+            return structuredClone(definition);
+        try {
+            const options = structuredClone(Validator.assertMcpServerOptions(value));
+            return structuredClone(Validator.assertMcpServerDefinition({
+                ...definition,
+                ...options,
+            }));
+        }
+        catch (cause) {
+            throw actionError("definition-invalid", 400, `MCP server '${definition.name}' has invalid enable options.`, { alias: definition.name, retryable: false }, cause);
+        }
+    }
+    async #setEnabled(workspaceId, params, enabled) {
         return this.#serialize(workspaceId, async () => {
-            const name = requiredString(params, "name");
+            assertActionKeys(params, enabled ? ["alias", "overlay", "options"] : ["alias"]);
+            const alias = requiredString(params, "alias");
             const snapshot = this.#snapshot(workspaceId);
-            const definition = this.#effective(snapshot.state).get(name);
-            if (definition === undefined) {
-                throw actionError("server-not-found", 404, `MCP server '${name}' is not attached to this workspace.`, { workspaceId, name, retryable: false });
+            const current = this.#available(snapshot.state).get(alias);
+            const configured = enabled
+                ? this.#overlayDefinitions(snapshot.state, params.overlay).get(alias)
+                : undefined;
+            if (current === undefined && configured === undefined) {
+                throw actionError("server-not-found", 404, `MCP server alias '${alias}' is not available in this workspace.`, { workspaceId, alias, retryable: false });
+            }
+            if (current === undefined && !enabled)
+                throw new Error("Disabled MCP target is absent.");
+            const candidate = configured ?? current?.definition;
+            if (candidate === undefined)
+                throw new Error("Enabled MCP target is absent.");
+            const definition = enabled
+                ? this.#definitionWithOptions(candidate, params.options)
+                : structuredClone(candidate);
+            const attachment = snapshot.attachments.get(alias);
+            const retryUnavailable = enabled
+                && current?.enabled === true
+                && sameDefinition(current.definition, definition)
+                && attachment?.kind === "unavailable";
+            const definitionChanged = current === undefined
+                || !sameDefinition(current.definition, definition);
+            if (current?.enabled === enabled && !definitionChanged && !retryUnavailable) {
+                if (attachment?.kind === "authorization-required") {
+                    return {
+                        status: 202,
+                        authorization: { url: attachment.authorizationUrl },
+                    };
+                }
+                return { status: 200, server: this.#summary(alias, current, attachment) };
             }
-            const result = await this.#applyState(workspaceId, snapshot.state, {
-                force: new Set([name]),
+            const state = retryUnavailable
+                ? cloneState(snapshot.state)
+                : enabled
+                    ? this.#stateWithDefinition(snapshot.state, alias, definition, true)
+                    : this.#stateWithEnabled(snapshot.state, alias, current, false);
+            const result = await this.#applyState(workspaceId, state, {
+                ...(retryUnavailable ? { force: new Set([alias]) } : {}),
                 authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
             });
             if (result.authorization !== undefined) {
-                await this.#setPending(workspaceId, name, {
-                    operation: "reconnect",
-                    expectedDefinition: structuredClone(definition.definition),
-                    definition,
+                await this.#setPending(workspaceId, alias, {
+                    operation: "enable",
+                    expectedState: structuredClone(snapshot.state.servers[alias] ?? null),
+                    expectedDefinition: structuredClone(current?.definition ?? null),
+                    expectedEnabled: current?.enabled ?? false,
+                    definition: {
+                        definition: structuredClone(definition),
+                        source: this.#definitionSource(alias, definition),
+                    },
                     connection: result.authorization.connection,
                     authorizationUrl: result.authorization.authorizationUrl,
                 });
@@ -506,43 +661,86 @@ export default class Module {
                     authorization: { url: result.authorization.authorizationUrl },
                 };
             }
-            const attached = this.#snapshot(workspaceId).attachments.get(name);
-            if (attached === undefined)
-                throw new Error("Reconnected MCP attachment is absent.");
-            await this.#clearPending(workspaceId, name, attached.connection);
-            return { status: 200, server: this.#summary(name, attached) };
+            await this.#clearPending(workspaceId, alias);
+            const committed = this.#snapshot(workspaceId);
+            const committedDefinition = this.#available(committed.state).get(alias);
+            if (committedDefinition === undefined)
+                throw new Error("Committed MCP definition is absent.");
+            return {
+                status: 200,
+                server: this.#summary(alias, committedDefinition, committed.attachments.get(alias)),
+            };
         });
     }
-    #oauthCompletionState(workspaceId, name, pending) {
+    async #remove(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            assertActionKeys(params, ["alias"]);
+            const alias = requiredString(params, "alias");
+            const snapshot = this.#snapshot(workspaceId);
+            const available = this.#available(snapshot.state).get(alias);
+            if (available === undefined) {
+                throw actionError("server-not-found", 404, `MCP server alias '${alias}' is not available in this workspace.`, { workspaceId, alias, retryable: false });
+            }
+            if (available.source === "service") {
+                throw actionError("server-service-owned", 409, `MCP server alias '${alias}' is service-owned and can be disabled, not removed.`, { workspaceId, alias, recovery: `Use workspace.mcp.disable for '${alias}'.`, retryable: false });
+            }
+            const state = cloneState(snapshot.state);
+            const service = this.#defaults.get(alias);
+            if (service === undefined) {
+                delete state.servers[alias];
+            }
+            else {
+                state.servers[alias] = {
+                    kind: "service",
+                    enabled: false,
+                };
+            }
+            await this.#applyState(workspaceId, state, {
+                authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
+            });
+            await this.#clearPending(workspaceId, alias);
+            return { status: 200, alias, removed: true };
+        });
+    }
+    #oauthCompletionState(workspaceId, alias, pending) {
         const snapshot = this.#snapshot(workspaceId);
-        const current = this.#effective(snapshot.state).get(name)?.definition ?? null;
+        const available = this.#available(snapshot.state).get(alias);
+        const current = available?.definition ?? null;
         const expected = pending.expectedDefinition;
-        if ((expected === null && current !== null)
-            || (expected !== null && (current === null || !sameDefinition(expected, current)))) {
-            throw actionError("oauth-target-conflict", 409, `MCP server '${name}' changed while its OAuth authorization was pending.`, {
+        if (!sameServerState(snapshot.state.servers[alias] ?? null, pending.expectedState)
+            || (expected === null && current !== null)
+            || (expected !== null && (current === null || !sameDefinition(expected, current)))
+            || (available?.enabled ?? false) !== pending.expectedEnabled) {
+            throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, {
                 workspaceId,
-                name,
+                alias,
                 recovery: "Start authorization again from the server's current definition.",
                 retryable: false,
             });
         }
-        const state = cloneState(snapshot.state);
-        if (pending.operation === "attach" || pending.operation === "replace") {
-            state.servers[name] = {
-                kind: "attached",
+        if (pending.operation === "add") {
+            const state = cloneState(snapshot.state);
+            state.servers[alias] = {
+                kind: "workspace",
                 definition: structuredClone(pending.definition.definition),
+                enabled: true,
             };
+            return state;
         }
-        return state;
+        return this.#stateWithDefinition(snapshot.state, alias, pending.definition.definition, true);
     }
     async #completeOAuth(workspaceId, params) {
         return this.#serialize(workspaceId, async () => {
-            const name = requiredString(params, "name");
+            assertActionKeys(params, ["alias", "callbackUrl"]);
+            const alias = requiredString(params, "alias");
             const callbackUrl = requiredString(params, "callbackUrl");
-            const key = this.#pendingKey(workspaceId, name);
+            const key = this.#pendingKey(workspaceId, alias);
             const pending = this.#pending.get(key);
             if (pending === undefined) {
-                throw actionError("oauth-not-pending", 404, `MCP server '${name}' has no pending OAuth authorization.`, { workspaceId, name, retryable: false });
+                // {§oauth-lifetime} — restart during pending authorization
+                // surfaces as a factual not-pending state, never a secret replay.
+                throw actionError("oauth-not-pending", 404, `MCP server '${alias}' has no pending OAuth authorization.`, { workspaceId, alias, retryable: false });
             }
             if (pending.prepared === undefined) {
                 try {
@@ -554,23 +752,30 @@ export default class Module {
                     pending.prepared = prepared;
                 }
                 catch (cause) {
-                    throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${name}' could not be completed.`, { workspaceId, name, retryable: false }, cause);
+                    throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${alias}' could not be completed.`, { workspaceId, alias, retryable: false }, cause);
                 }
             }
-            const state = this.#oauthCompletionState(workspaceId, name, pending);
+            const state = this.#oauthCompletionState(workspaceId, alias, pending);
             await this.#applyState(workspaceId, state, {
-                force: new Set([name]),
-                prepared: new Map([[name, pending.prepared]]),
+                force: new Set([alias]),
+                prepared: new Map([[alias, pending.prepared]]),
                 authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
             });
             this.#pending.delete(key);
-            const attached = this.#snapshot(workspaceId).attachments.get(name);
-            if (attached === undefined)
+            const committed = this.#snapshot(workspaceId);
+            const attached = committed.attachments.get(alias);
+            if (attached === undefined || attached.kind !== "active") {
                 throw new Error("Authorized MCP attachment is absent.");
-            return { status: 200, server: this.#summary(name, attached) };
+            }
+            const available = this.#available(committed.state).get(alias);
+            if (available === undefined)
+                throw new Error("Authorized MCP definition is absent.");
+            return { status: 200, server: this.#summary(alias, available, attached) };
         });
     }
     async #complete(workspaceId, params) {
+        assertActionKeys(params, ["server", "ref", "argument", "context"]);
         const server = requiredString(params, "server");
         const attachment = this.#snapshot(workspaceId).attachments.get(server);
         if (attachment === undefined || attachment.kind !== "active") {
@@ -598,14 +803,14 @@ export default class Module {
         const executor = new McpExecutor({ runtime: name, glyph: "🔌" }, attachment.connection, {
             tools: attachment.definition.tools ?? null,
             read: attachment.definition.read ?? [],
-        });
+        }, this.#summaries.tools);
         const availability = await executor.requireAvailable();
         const refreshed = {
             ...attachment,
             executor,
             runtime: {
                 namespaceOwner: OWNER,
-                decl: runtimeDecl(name),
+                decl: runtimeDecl(name, serverSummary(name, executor.catalog, this.#summaries.servers.get(name)), this.#expanded.has(name)),
                 executor,
                 availability,
                 scheme: new McpResources(name, attachment.connection, executor.catalog),
@@ -656,7 +861,9 @@ export default class Module {
         const connections = new Set();
         for (const snapshot of this.#workspaces.values()) {
             for (const attachment of snapshot.attachments.values()) {
-                connections.add(attachment.connection);
+                const connection = attachmentConnection(attachment);
+                if (connection !== undefined)
+                    connections.add(connection);
             }
         }
         for (const pending of this.#pending.values())