@plurnk/plurnk-mcp 1.26.0 → 1.28.0

package/README.md

@@ -155,7 +155,8 @@ so each search runs under the proposal policy.
 | MCP surface | Plurnk surface |
 |---|---|
 | Server tools | `worker:///_plurnk/tools/<server>.md` family summary |
-| Enabled tool | Exact `worker:///_plurnk/tools/<server>/<encoded-tool>.md` document and ````` ````server (tool) ````` |
+| Complete tool definitions | `worker:///_plurnk/tools/<server>.json`: `{"tools":[...]}`, readable on demand with ordinary patterns |
+| Enabled tool | `server (tool)` invocation in the family document; full input schema at `worker:///_plurnk/tools/<server>/<encoded-tool>.json` |
 | Resource catalog | `server:///` or `server:///resources` |
 | Resource | `server:///resources/<encoded-uri>` through ordinary `FIND` and `READ` |
 | Prompt catalog | `server:///prompts` |
@@ -182,14 +183,21 @@ client.
 
 HTTP servers support bearer references, client credentials, and interactive
 OAuth; stdio servers read their credentials from the environment. A server that
-needs interactive OAuth comes up `authorization-required`, and enabling it
-returns `202` with `definition.authorization.url` without
-publishing a partial server. The terminal client's `/mcp oauth <alias>` receives
-a configured HTTP loopback IP callback and opens the browser; supplying the
+challenges an anonymous connection comes up `authorization-required`, without
+publishing partial tools. A URL-only definition is sufficient; no callback
+port needs to be configured. The terminal client's `/mcp oauth <alias>` binds
+an available loopback port and calls `workspace.mcp.oauth.begin` before opening
+the returned authorization URL. A fixed OAuth redirect, if configured, is
+respected. Supplying the
 callback URL explicitly also works for remote/headless use. The client submits
-the complete URL through `workspace.mcp.oauth.complete`. PKCE,
+the complete URL through `workspace.mcp.oauth.complete`. Its `202` acknowledges
+sign-in; tools activate at the next safe workspace boundary, without another
+callback submission. `list` shows their current readiness. PKCE,
 issuer and resource validation, refresh, scope escalation, and credentials
-remain inside the host connection.
+remain inside the host connection. Callback addresses and credentials never
+replace the saved definition. `enable` retries a connection; it does not replace
+user sign-in. Rejected configured credentials are reported as authentication
+failures rather than retryable server downtime.
 
 ## Verification
 

package/SPEC.md

@@ -392,12 +392,13 @@ server needs, and its provenance names the registry and the server's `name@versi
 | The complete connection definition is invalid | `definition-invalid` | 400 |
 | The alias differs from the definition's name | `alias-mismatch` | 400 |
 
-Two protocol continuations remain MCP-registered workspace actions beneath the
+Protocol continuations remain MCP-registered workspace actions beneath the
 common grammar:
 
 | Action | Parameters | Result / effect |
 |---|---|---|
-| `workspace.mcp.oauth.complete` | `alias`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, and re-enables the alias through the coordinator ({§oauth-continuation}); the result is the common mutation result. |
+| `workspace.mcp.oauth.begin` | `alias`, `redirectUrl` | Begin sign-in using a client-owned callback, without changing the connection definition; publish the pending URL through the coordinator. An active alias is returned unchanged. |
+| `workspace.mcp.oauth.complete` | `alias`, `callbackUrl` | Validates and exchanges the pending callback through the SDK, returning `McpOAuthCompletionResult` (`202`, `alias`); ordinary capability refresh publishes the authenticated tools at the next safe boundary ({§oauth-continuation}). |
 | `workspace.mcp.complete` | `server`, `ref`, `argument`; optional `context` | Requests negotiated prompt/resource-template argument completion for a client-owned interaction. |
 
 Expected preparation failures cross the boundary as MCP-management Problems
@@ -408,6 +409,9 @@ Worker's own accepted mutation publishes them as unavailable
 | Endpoint condition | Problem |
 |---|---|
 | Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and its `type` without exposing credentials |
+| HTTP 401 without configured credentials | Enabled `authorization-required`, no runtime and no URL until the client begins sign-in |
+| HTTP 401 with configured credentials | `502 server-authentication-failed`, non-retryable, with `upstreamStatus: 401`; credentials are not replaced by interactive OAuth |
+| Sign-in discovery lacks validated authorization metadata or a usable client-registration method | `502 oauth-metadata-unavailable` or `oauth-registration-unavailable`, non-retryable; retain the definition and surface the setup boundary, not retryable downtime |
 | The endpoint answers with a redirect | `502 server-redirected`, non-retryable ({§mcp-redirect-refused}) |
 | An operator setting of the alias is invalid | `422 server-settings-invalid`, non-retryable ({§mcp-server-settings}) |
 | Client-credentials grant rejected by the authorization server | `502 oauth-client-credentials-failed`, non-retryable; names the server and client id, never the secret ({§oauth-client-credentials}) |
@@ -416,21 +420,68 @@ Resource and prompt failures retain one caught remote diagnostic only through
 the executor-owned `PLURNK_EXECS_ERROR_DETAIL_LIMIT` bound; complete causes stay
 in daemon diagnostics. No MCP resource Problem admits an unbounded SDK message.
 
-§oauth-continuation Interactive preparation publishes the alias as enabled and
-`authorization-required` with its URL; it publishes no runtime. The adapter
-retains one pending candidate per `(workspace, alias)` holding the challenged
-connection and one workspace residency lease; a new challenge for the alias
-supersedes and releases the previous one ({§oauth-lifetime}).
-`oauth.complete` accepts the complete callback URL so state, `code`, and
-`iss` remain one parsing unit; it finishes the pending connection's
-authorization, prepares its active attachment, and re-enables the alias through
-the coordinator, whose publication consumes the prepared attachment and
-releases the lease. A callback for a superseded attempt fails as invalid; a
+§oauth-continuation A URL-only HTTP definition is sufficient to reach the client
+sign-in handoff. An unauthenticated 401 publishes `authorization-required` with
+an empty `authorization` object, not retryable downtime. No browser is opened,
+client is registered, or workspace lease retained merely for that challenge.
+The client binds its callback before `oauth.begin`; absent an explicitly
+configured redirect, it obtains an ephemeral loopback port (RFC 8252 §7.3).
+The MCP SDK owns metadata discovery, registration, PKCE and token exchange.
+An explicit OAuth definition may supply scope and client-registration metadata;
+its optional fixed redirect is respected, never silently rewritten. Bearer,
+client-credentials and Authorization-header configurations cannot be replaced
+by `oauth.begin`. Callback addresses and acquired credentials are session state,
+not changes to the persisted definition.
+
+```mermaid
+sequenceDiagram
+    Model->>MCP: add URL-only definition
+    MCP-->>Model: authorization-required
+    User->>Client: sign in to alias
+    Client->>Client: bind callback
+    Client->>MCP: oauth.begin(alias, redirectUrl)
+    MCP-->>Client: authorization URL
+    Client->>User: open consent page
+    User->>Client: browser callback
+    Client->>MCP: oauth.complete(alias, callbackUrl)
+    MCP-->>Client: 202 sign-in accepted; activation pending
+    MCP-->>Model: active tools through normal publication
+```
+
+`oauth.begin` prepares an authorization attempt without enabling the alias or
+waiting for workspace quiescence. It returns `202` with an `authorization.url`
+when consent is required, `202` without that field when an accepted connection
+awaits publication, or `200` when tools are already active. These results name
+the alias, not a capability snapshot. The adapter retains one pending candidate
+per `(workspace, alias)` holding the connection and one workspace residency
+lease. An unchanged publication preserves that independent attempt; a new
+challenge supersedes it ({§oauth-lifetime}).
+Concurrent begin requests for one alias are refused; a later begun attempt
+supersedes the prior one unless its grant is already accepted and awaiting
+publication. An in-flight begin cannot attach after disable,
+remove or definition replacement. `oauth.complete` accepts the complete callback URL so state, `code`, and
+`iss` remain one parsing unit. Grant acceptance returns without waiting for
+workspace quiescence; it is not a configuration mutation and cannot re-enable
+an alias. The existing catalog-refresh path prepares and publishes the current
+enabled definitions, then consumes the candidate and releases its lease.
+The accepted result does not claim tool readiness: `list` reports the current
+published snapshot, including any subsequent preparation failure. A callback
+for a superseded attempt fails as invalid; a
 committed attachment that no longer matches the pending definition fails
 with a conflict instead of replaying a stale snapshot. A missing, expired,
 mismatched, or replayed callback fails without exposing attacker-owned OAuth
 error text.
 
+| Callback boundary | Result |
+|---|---|
+| Active workspace | Accept the valid grant without waiting for the held turn; queue publication through the coordinator's ordinary workspace gate. |
+| Identical concurrent or accepted-but-unpublished callback | Share the same acceptance; exchange the one-time code once. |
+| Different callback for that accepted attempt | Reject; never borrow another callback's acceptance. |
+| Disable, remove, or replacement | Current definitions win; the old candidate cannot restore a withdrawn server. |
+| Publication failure | Do not claim active tools; retain the accepted candidate for normal refresh/enable retry, without another code exchange. |
+| Preparation failure published as unavailable | Preserve the preparation diagnostic; release the pending lease and close its unused connection. |
+| Callback after publication | The attempt has been consumed; `404 oauth-not-pending`. |
+
 ## §oauth-lifetime Interactive OAuth lifetime and reauthorization
 
 Interactive OAuth state is deliberately ephemeral and process-memory: client
@@ -450,7 +501,7 @@ as an accidental failure.
 | Pending authorization | One pending candidate per `(workspace, alias)`; a new challenge or customized enable cancels and replaces it. A callback from a superseded attempt fails state validation instead of cross-completing. |
 | Client disconnect | Does not touch the pending candidate; it can still be completed, or replaced by a fresh request. |
 | Daemon restart during pending | The candidate is lost: nothing was durable, no attachment publishes, and `oauth.complete` answers `404 oauth-not-pending`. Start authorization again. |
-| Daemon restart after authorization | The durable definition rehydrates but tokens are gone; the attachment publishes `authorization-required` and enable returns status `202` with `definition.authorization.url` in the common mutation result. The operator reauthorizes. |
+| Daemon restart after authorization | The durable definition rehydrates but tokens are gone; a challenged attachment publishes `authorization-required` and enable returns `202`. A URL is present only when a callback is already configured. The operator reauthorizes. |
 | Token expiry | An expired access token surfaces as one unauthorized response; the SDK re-acquires via `refresh_token` when one was issued, otherwise re-enters interactive authorization. |
 | Refresh | Happens only against the issuer bound during the original authorization; the refreshed token replaces the in-memory token. |
 | Workspace disable/remove | Closes the attachment and clears its pending candidate; no durable secret deletion is needed because nothing secret is durable. |
@@ -676,10 +727,11 @@ mediate a `postMessage` JSON-RPC `ui/` dialect, proxy app-initiated tool
 calls with consent, and own teardown. No Plurnk client can enforce that
 sandbox today (the terminal cannot), the daemon is not a second
 application platform, and AG-UI has no standard Apps projection — inventing
-a private event stream to carry Apps is rejected. Tool descriptions carrying
-`_meta.ui` metadata project into Plurnk without it: model-facing summaries
-derive only from name, description, title, and input schema, and no UI
-resource is fetched or preloaded. The capability matrix keeps the extension
+a private event stream to carry Apps is rejected. Compact tool summaries and
+invocations derive only from name, description, title, and input schema,
+without `_meta.ui`. The on-demand raw tool catalog preserves `_meta` as inert
+data: no UI resource is fetched or preloaded, permissions are not granted,
+and reading a definition does not activate an App. The capability matrix keeps the extension
 non-advertised ({§mcp-capability-matrix}). Re-evaluate only when a
 sandbox-capable client exists and a standard AG-UI projection is agreed;
 even then the capability would be per-client-advertised, never daemon-wide.
@@ -702,6 +754,7 @@ it as a skill. The design review is tracked in #654.
 |---|---|
 | Server | One registered executor family, `worker:///_plurnk/tools/<server>.md`, and matching resource scheme |
 | Enabled tool | One annotated call in the compact family document plus one exact `worker:///_plurnk/tools/<server>/<encoded-tool>.json` input-contract document |
+| Complete tool definitions | `worker:///_plurnk/tools/<server>.json`, containing `{"tools":[...]}` from the same effective snapshot |
 | Tool survey | Ordinary FIND summary metadata from the standard executable-tool resource tree |
 | Resource catalog | `<server>:///` and `<server>:///resources` |
 | Resources | `<server>:///resources` and encoded resource-URI descendants |
@@ -724,10 +777,20 @@ The compact family document contains annotated, copyable tool invocations with
 shallow required-field previews and alias-scoped schema links. Each linked child
 preserves the complete remote description and raw input schema, without
 reconstructing property tables or expanding nested constraints into the preview.
-Output schemas do not enter model teaching; the returned value remains ordinary evidence. Disabled names
+Output schemas do not enter compact invocation teaching; the returned value remains ordinary evidence. Disabled names
 appear in no model teaching, and there is no MCP-specific FIND,
 READ, authority-root, or other model discovery mechanism for tools.
 
+Each registry entry carries the original MCP `Tool` object as its
+{§executor-tool-catalog} definition. The catalog preserves full descriptions,
+input and output schemas, annotations, icons, and metadata as received through
+the MCP client, without synthesized fields or schema expansion. It contains
+the selected tools from all catalog pages, sorted by tool name, not the JSON-RPC
+envelope, pagination cursors, or transport cache controls. The Markdown family
+document links to it; ordinary READ and JSONPath can inspect one tool or the
+whole catalog. Reading the catalog performs no additional MCP discovery and
+does not inject its contents into turn 0.
+
 Core validates the exact target and the selected tool's invocation before
 effect admission. `McpExecutor.run()` independently rejects a target outside
 the same snapshot before issuing `tools/call`. The server's empty-authority
@@ -763,6 +826,12 @@ stdio/Streamable HTTP servers are composition evidence only.
 | `tool-reported-error` | 502 | The MCP tool reported an error (the tool call failed). |
 | `invalid-tool-arguments` | 400 | The tool arguments are not one JSON object. Recovery: One JSON object per MCP tool call; a second call is a second fence. |
 | `oauth-client-credentials-failed` | 502 | MCP server '*name*' rejected the client-credentials grant; check the configured client credentials and issuer. |
+| `server-authentication-failed` | 502 | MCP server '*name*' rejected authentication (HTTP 401). |
+| `oauth-metadata-unavailable` | 502 | MCP OAuth requires validated authorization-server metadata; legacy endpoint inference is not supported. |
+| `oauth-registration-unavailable` | 502 | The authorization server exposes no usable client registration: configure pre-registration or advertised CIMD; its metadata does not advertise a Dynamic Client Registration endpoint. |
+| `oauth-redirect-invalid` | 400 | The OAuth callback must use HTTPS or HTTP loopback with a usable port. |
+| `oauth-configuration-conflict` | 409 | MCP server '*alias*' is not configured for this interactive OAuth callback. |
+| `oauth-busy` | 409 | MCP server '*alias*' is already starting authorization. |
 | `parameters-invalid` | 400 | Unsupported parameter(s): *names*. |
 | `server-settings-invalid` | 422 | MCP server '*name*' has invalid operator settings: *cause*. |
 | `server-busy` | 409 | MCP server '*name*' has *n* active request(s). |

package/dist/Module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Module.d.ts","sourceRoot":"","sources":["../src/Module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Module.d.ts","sourceRoot":"","sources":["../src/Module.ts"],"names":[],"mappings":"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"}

package/dist/Module.js

@@ -6,18 +6,19 @@
 import { fileURLToPath } from "node:url";
 import { readDefinition } from "./definition.js";
 import { isDeepStrictEqual } from "node:util";
+import { SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
 import { Problems, } from "@plurnk/plurnk-contracts";
 import ServerConnection, { AuthorizationRequiredError, isClientCredentialsRejection, McpRedirectError, } from "./client.js";
 import { configuredDefinitions, connectTimeoutMs, expandedServerNames, retryDelayMs, retryPacing, registrySettings, serverSettings, } from "./config.js";
 import { RegistryError, registryEntries, searchRegistry } from "./registry.js";
 import McpExecutor, { runtimeDecl, runtimeServerSummary } from "./McpExecutor.js";
 import McpResources from "./McpResources.js";
+import { OAuthSetupError } from "./oauth.js";
 const OWNER = "@plurnk/plurnk-mcp";
 const FAMILY = "mcp";
 const NONEMPTY_STRING = { type: "string", minLength: 1 };
 const OPEN_OBJECT = { type: "object", additionalProperties: true };
 const MCP_DEFINITION = { $ref: "https://schemas.plurnk.xyz/v0/McpServerDefinition.json" };
-const MUTATION_RESULT = { $ref: "https://schemas.plurnk.xyz/v0/FunctionalityMutationResult.json" };
 const actionInput = (properties, required = []) => ({
     type: "object",
     additionalProperties: false,
@@ -56,6 +57,9 @@ const preparationError = (definition, authorization, cause, closeCause) => {
     const completeCause = closeCause === undefined
         ? cause
         : new AggregateError([cause, closeCause], `MCP server '${definition.name}' preparation and cleanup failed.`);
+    const setup = causeOf(cause, OAuthSetupError);
+    if (setup !== undefined)
+        return actionError(setup.code, 502, setup.message, { server: definition.name, retryable: false }, completeCause);
     // {§oauth-client-credentials} — a rejected grant is an authorization fact,
     // never a generic unavailability.
     if (authorization?.type === "client-credentials" && isClientCredentialsRejection(cause)) {
@@ -74,6 +78,10 @@ const preparationError = (definition, authorization, cause, closeCause) => {
     if (redirect !== undefined) {
         return actionError("server-redirected", 502, redirect.message, { server: definition.name, url: redirect.url, ...(redirect.location === null ? {} : { location: redirect.location }), retryable: false }, completeCause);
     }
+    const http = causeOf(cause, SdkHttpError);
+    if (http?.status === 401 || causeOf(cause, UnauthorizedError) !== undefined) {
+        return actionError("server-authentication-failed", 502, `MCP server '${definition.name}' rejected authentication (HTTP 401).`, { server: definition.name, upstreamStatus: 401, retryable: false }, completeCause);
+    }
     return actionError("server-unavailable", 502, `Configured MCP server '${definition.name}' is unavailable.`, {
         server: definition.name,
         type: definition.type,
@@ -143,6 +151,7 @@ export default class Module {
     #attachments = new Map();
     #identities = new Map();
     #pending = new Map();
+    #authorizing = new Set();
     #dirty = new Map();
     #connections = new Set();
     #refreshTimers = new Map();
@@ -181,12 +190,20 @@ export default class Module {
             refreshIfChanged: (identity) => this.#refreshIfChanged(identity),
         });
         // Protocol continuations beneath the common grammar.
+        seam.registerModuleAction({
+            name: "workspace.mcp.oauth.begin",
+            scope: "workspace",
+            residency: "required",
+            inputSchema: actionInput({ alias: NONEMPTY_STRING, redirectUrl: NONEMPTY_STRING }, ["alias", "redirectUrl"]),
+            outputSchema: { $ref: "https://schemas.plurnk.xyz/v0/McpOAuthBeginResult.json" },
+            handler: (params, context) => this.#beginOAuth(workspaceIdentityOf(context), params),
+        });
         seam.registerModuleAction({
             name: "workspace.mcp.oauth.complete",
             scope: "workspace",
             residency: "required",
             inputSchema: actionInput({ alias: NONEMPTY_STRING, callbackUrl: NONEMPTY_STRING }, ["alias", "callbackUrl"]),
-            outputSchema: MUTATION_RESULT,
+            outputSchema: { $ref: "https://schemas.plurnk.xyz/v0/McpOAuthCompletionResult.json" },
             handler: (params, context) => this.#completeOAuth(workspaceIdentityOf(context), params),
         });
         seam.registerModuleAction({
@@ -299,7 +316,7 @@ export default class Module {
             throw new AggregateError(errors, "MCP connection shutdown failed");
     }
     // The attachment keeps the exact symbolic definition; resolved launch values never enter state.
-    async #prepareAttachment(workspaceId, binding, connection) {
+    async #prepareAttachment(workspaceId, binding, connection, oauthRedirectUrl) {
         const { definition, context } = binding;
         this.#assertOpen();
         // {§mcp-server-settings} — the operator's settings for this alias; a bad one isolates this server.
@@ -319,6 +336,7 @@ export default class Module {
             // {§mcp-launch-environment} — a configured server inherits the operator's environment beneath the
             // workspace layer, as every MCP client launches one; the model's command ceiling is not its base.
             candidate ??= new ServerConnection(definition, environment(this.#env), {
+                ...(oauthRedirectUrl === undefined ? {} : { oauthRedirectUrl }),
                 ...(definition.type === "stdio" && definition.cwd === undefined && context === undefined ? { cwd: await this.#stateDirectory(workspaceId, `${OWNER}/${definition.name}`) } : {}),
                 ...(context === undefined ? {} : { plugin: context }),
                 environment: environment(this.#operatorEnvironment()),
@@ -412,7 +430,7 @@ export default class Module {
                     && force !== name
                     && !this.#dirty.has(this.#pendingKey(workspaceId, name))
                     && sameBinding(existing, binding)
-                    && !(pending?.prepared !== undefined)) {
+                    && pending?.prepared === undefined && pending?.authorized !== true) {
                     next.set(name, existing);
                     continue;
                 }
@@ -421,7 +439,7 @@ export default class Module {
                 const catalogOnly = existing !== undefined
                     && force !== name
                     && sameBinding(existing, binding)
-                    && !(pending?.prepared !== undefined)
+                    && pending?.prepared === undefined && pending?.authorized !== true
                     && heldConnection !== undefined;
                 if (pending?.prepared !== undefined && sameBinding(pending, binding)) {
                     attachment = pending.prepared;
@@ -442,8 +460,9 @@ export default class Module {
                     }
                 }
                 else {
+                    const authorized = pending?.authorized === true && sameBinding(pending, binding);
                     try {
-                        attachment = await this.#prepareAttachment(workspaceId, binding);
+                        attachment = await this.#prepareAttachment(workspaceId, binding, authorized ? pending.connection : undefined);
                     }
                     catch (cause) {
                         this.#assertOpen();
@@ -454,7 +473,9 @@ export default class Module {
                         console.error(`MCP server '${name}' unavailable: ${refusal.problem.detail}`, refusal.cause ?? refusal);
                     }
                     // Only a connection this attempt opened is the attempt's to close on abort.
-                    if (attachment.kind !== "unavailable")
+                    if (authorized)
+                        consumedPending.set(name, pending);
+                    else if (attachment.kind !== "unavailable")
                         fresh.push(attachment);
                 }
                 next.set(name, attachment);
@@ -478,7 +499,10 @@ export default class Module {
                     outcomes.set(name, { state: "unavailable", problem: attachment.problem });
                     break;
                 case "authorization-required":
-                    outcomes.set(name, { state: "authorization-required", authorization: { url: attachment.authorizationUrl } });
+                    outcomes.set(name, {
+                        state: "authorization-required",
+                        authorization: attachment.authorizationUrl === undefined ? {} : { url: attachment.authorizationUrl },
+                    });
                     break;
             }
         }
@@ -507,15 +531,21 @@ export default class Module {
                     .flatMap((attachment) => attachmentConnection(attachment) ?? [])
                     .filter((connection) => !retained.has(connection) && !pendingConnections.has(connection));
                 for (const [name, pending] of consumedPending) {
-                    this.#pending.delete(this.#pendingKey(workspaceId, name));
+                    const key = this.#pendingKey(workspaceId, name);
+                    if (this.#pending.get(key) === pending)
+                        this.#pending.delete(key);
                     pending.releaseWorkspace();
+                    if (!retained.has(pending.connection))
+                        obsolete.push(pending.connection);
                 }
-                // {§oauth-lifetime} Only the same pending connection can retain its authorization flow.
+                // {§oauth-lifetime} A client's challenge is independent of the published connection.
                 for (const [key, pending] of this.#pending) {
                     if (!key.startsWith(`${workspaceId}:`))
                         continue;
-                    const current = next.get(key.slice(`${workspaceId}:`.length));
-                    if (current?.kind === "authorization-required" && current.connection === pending.connection)
+                    const name = key.slice(`${workspaceId}:`.length);
+                    const current = next.get(name);
+                    if (current !== undefined && current.kind !== "active" && sameBinding(current, pending)
+                        && force !== name)
                         continue;
                     this.#pending.delete(key);
                     pending.releaseWorkspace();
@@ -523,24 +553,18 @@ export default class Module {
                         obsolete.push(pending.connection);
                 }
                 for (const [name, attachment] of next) {
-                    if (attachment.kind !== "authorization-required")
+                    if (attachment.kind !== "authorization-required" || attachment.authorizationUrl === undefined)
                         continue;
                     const key = this.#pendingKey(workspaceId, name);
                     const current = this.#pending.get(key);
-                    if (current?.connection === attachment.connection)
+                    if (current !== undefined)
                         continue;
                     this.#pending.set(key, {
                         definition: attachment.definition,
                         ...(attachment.context === undefined ? {} : { context: attachment.context }),
                         connection: attachment.connection,
-                        authorizationUrl: attachment.authorizationUrl,
                         releaseWorkspace: this.#retain(workspaceId),
                     });
-                    if (current !== undefined) {
-                        current.releaseWorkspace();
-                        if (!retained.has(current.connection))
-                            obsolete.push(current.connection);
-                    }
                 }
                 if (obsolete.length > 0) {
                     try {
@@ -573,9 +597,68 @@ export default class Module {
         this.#identities.delete(workspaceId);
         await this.#closeOwned(connections);
     }
-    // {§oauth-continuation} — the callback finishes the pending connection's
-    // authorization, prepares its attachment, and re-enables the alias through
-    // the coordinator, which consumes the prepared attachment on publication.
+    // {§oauth-continuation} Client callback state travels with the prepared connection, not its definition.
+    async #beginOAuth(identity, params) {
+        assertActionKeys(params, ["alias", "redirectUrl"]);
+        const alias = requiredString(params, "alias");
+        const redirectUrl = requiredString(params, "redirectUrl");
+        const redirect = URL.parse(redirectUrl);
+        if (redirect === null || redirect.username || redirect.password || redirect.hash || redirect.port === "0"
+            || !(redirect.protocol === "https:" || (redirect.protocol === "http:" && ["127.0.0.1", "[::1]", "localhost"].includes(redirect.hostname)))) {
+            throw actionError("oauth-redirect-invalid", 400, "The OAuth callback must use HTTPS or HTTP loopback with a usable port.", { retryable: false });
+        }
+        const current = this.#attachments.get(identity.workspaceId)?.get(alias);
+        if (current === undefined)
+            throw actionError("server-not-connected", 409, `MCP server '${alias}' is not connected for this workspace.`, { retryable: false });
+        if (current.kind === "active")
+            return { status: 200, alias };
+        const definition = current.definition;
+        if (definition.type !== "streamable-http"
+            || (definition.authorization !== undefined && definition.authorization.type !== "oauth")
+            || Object.keys(definition.headers ?? {}).some((name) => name.toLowerCase() === "authorization")
+            || (definition.authorization?.redirectUrl !== undefined && definition.authorization.redirectUrl !== redirectUrl)) {
+            throw actionError("oauth-configuration-conflict", 409, `MCP server '${alias}' is not configured for this interactive OAuth callback.`, { retryable: false });
+        }
+        const key = this.#pendingKey(identity.workspaceId, alias);
+        if (this.#pending.get(key)?.authorized === true)
+            return { status: 202, alias };
+        if (this.#authorizing.has(key))
+            throw actionError("oauth-busy", 409, `MCP server '${alias}' is already starting authorization.`, { retryable: true });
+        this.#authorizing.add(key);
+        try {
+            const prepared = await this.#prepareAttachment(identity.workspaceId, current, undefined, redirectUrl);
+            if (prepared.kind === "unavailable")
+                throw new Error("OAuth preparation returned an unavailable attachment.");
+            if (this.#attachments.get(identity.workspaceId)?.get(alias) !== current) {
+                await this.#closeOwned([prepared.connection]);
+                throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, { workspaceId: identity.workspaceId, alias, recovery: "Start authorization again from the server's current definition.", retryable: false });
+            }
+            const previous = this.#pending.get(key);
+            const pending = {
+                ...prepared,
+                releaseWorkspace: this.#retain(identity.workspaceId),
+                ...(prepared.kind === "active" ? { prepared, authorized: true } : {}),
+            };
+            this.#pending.set(key, pending);
+            if (previous !== undefined) {
+                previous.releaseWorkspace();
+                if (previous.connection !== attachmentConnection(current))
+                    await this.#closeOwned([previous.connection]);
+            }
+            if (prepared.kind === "authorization-required") {
+                if (prepared.authorizationUrl === undefined)
+                    throw new Error("OAuth preparation with a callback omitted its authorization URL.");
+                return { status: 202, alias, authorization: { url: prepared.authorizationUrl } };
+            }
+            this.#dirty.set(key, Symbol());
+            this.#refreshCatalog(identity.workspaceId, alias);
+            return { status: 202, alias };
+        }
+        finally {
+            this.#authorizing.delete(key);
+        }
+    }
+    // {§oauth-continuation} — grant acceptance precedes ordinary catalog publication.
     async #completeOAuth(identity, params) {
         assertActionKeys(params, ["alias", "callbackUrl"]);
         const alias = requiredString(params, "alias");
@@ -588,23 +671,31 @@ export default class Module {
             throw actionError("oauth-not-pending", 404, `MCP server '${alias}' has no pending OAuth authorization.`, { workspaceId: identity.workspaceId, alias, retryable: false });
         }
         const current = this.#attachments.get(identity.workspaceId)?.get(alias);
-        if (current === undefined || current.kind !== "authorization-required" || !sameBinding(current, pending)) {
+        if (current === undefined || !sameBinding(current, pending)) {
             throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, { workspaceId: identity.workspaceId, alias, recovery: "Start authorization again from the server's current definition.", retryable: false });
         }
-        if (pending.prepared === undefined) {
+        if (pending.completion !== undefined) {
+            if (pending.completion.callbackUrl !== callbackUrl)
+                throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${alias}' could not be completed.`, { workspaceId: identity.workspaceId, alias, retryable: false });
+            return pending.completion.result;
+        }
+        const result = (async () => {
             try {
                 await pending.connection.finishAuthorization(callbackUrl);
-                const prepared = await this.#prepareAttachment(identity.workspaceId, pending, pending.connection);
-                if (prepared.kind !== "active")
-                    throw new Error("OAuth completion returned another authorization challenge.");
-                pending.prepared = prepared;
             }
             catch (cause) {
+                delete pending.completion;
                 throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${alias}' could not be completed.`, { workspaceId: identity.workspaceId, alias, retryable: false }, cause);
             }
-        }
-        const result = await this.#handleOrThrow().invoke("enable", { alias }, identity);
-        return result.body;
+            if (this.#pending.get(key) !== pending || this.#closed)
+                throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, { workspaceId: identity.workspaceId, alias, retryable: false });
+            pending.authorized = true;
+            this.#dirty.set(key, Symbol());
+            this.#refreshCatalog(identity.workspaceId, alias);
+            return { status: 202, alias };
+        })();
+        pending.completion = { callbackUrl, result };
+        return result;
     }
     async #complete(workspaceId, params) {
         assertActionKeys(params, ["server", "ref", "argument", "context"]);
@@ -635,25 +726,29 @@ export default class Module {
         const delay = retryDelayMs(retryPacing(this.#env), attempt);
         const timer = setTimeout(() => {
             this.#refreshTimers.delete(key);
-            const identity = this.#identities.get(workspaceId);
-            if (identity === undefined || this.#closed) {
-                this.#dirty.delete(key);
-                return;
-            }
-            void this.#handleOrThrow().refresh(identity).then(() => {
-                if (this.#dirty.has(key))
-                    this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
-            }).catch((error) => {
-                if (statusOf(error) === 409) {
-                    this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
-                    return;
-                }
-                console.error(`MCP server '${name}' capability refresh failed:`, error);
-            });
+            this.#refreshCatalog(workspaceId, name, attempt);
         }, delay);
         timer.unref();
         this.#refreshTimers.set(key, timer);
     }
+    #refreshCatalog(workspaceId, name, attempt = 0) {
+        const key = this.#pendingKey(workspaceId, name);
+        const identity = this.#identities.get(workspaceId);
+        if (identity === undefined || this.#closed) {
+            this.#dirty.delete(key);
+            return;
+        }
+        void this.#handleOrThrow().refresh(identity).then(() => {
+            if (this.#dirty.has(key))
+                this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
+        }).catch((error) => {
+            if (statusOf(error) === 409) {
+                this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
+                return;
+            }
+            console.error(`MCP server '${name}' capability refresh failed:`, error);
+        });
+    }
     #clearCatalogRefresh(key) {
         this.#dirty.delete(key);
         clearTimeout(this.#refreshTimers.get(key));